@oga-mcp/server 1.0.0

package/dist/tools/intelligence-format.js

@@ -0,0 +1,197 @@
+/**
+ * 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 { formatAreaProfileAsText } from "./signals-format.js";
+function formatRankAreas(plan, results) {
+    const params = plan.params;
+    const sortLabel = params.sort_by
+        ? `${params.sort_by.signal} (${params.sort_by.mode ?? "percentile"} ${params.sort_by.direction ?? "desc"})`
+        : params.signal ?? "default";
+    const rows = (Array.isArray(results) ? results : []);
+    const lines = [];
+    lines.push(`**Ranking by:** ${sortLabel}`);
+    if (params.country)
+        lines.push(`**Scope:** ${params.country}`);
+    if (params.lad)
+        lines.push(`**LAD:** ${params.lad}`);
+    if (params.limit)
+        lines.push(`**Limit:** ${params.limit}`);
+    lines.push("");
+    if (rows.length === 0) {
+        lines.push("No areas matched.");
+        return lines.join("\n");
+    }
+    lines.push("| Rank | LSOA | Value | Percentile |");
+    lines.push("|---|---|---|---|");
+    let rank = 1;
+    for (const r of rows) {
+        const v = r.value === null || r.value === undefined ? "—" : String(r.value);
+        const p = r.percentile === null || r.percentile === undefined ? "—" : `${r.percentile}th`;
+        lines.push(`| ${rank} | ${r.geo_code} | ${v} | ${p} |`);
+        rank++;
+    }
+    return lines.join("\n");
+}
+function formatGetArea(results) {
+    /* results === null means the area didn't resolve. */
+    if (results === null)
+        return "Area could not be resolved.";
+    return formatAreaProfileAsText(results);
+}
+function formatScoreArea(results) {
+    if (results === null)
+        return "Area could not be resolved.";
+    const r = results;
+    const lines = [];
+    lines.push(`**${r.area}** · preset ${r.preset} · **${r.score}/100** · ${r.area_type} · confidence ${(r.confidence * 100).toFixed(0)}%`);
+    lines.push(`Engine version: ${r.engine_version}`);
+    lines.push("");
+    if (r.dimensions && r.dimensions.length > 0) {
+        lines.push("| Dimension | Score | Weight | Confidence |");
+        lines.push("|---|---|---|---|");
+        for (const d of r.dimensions) {
+            lines.push(`| ${d.label} | ${d.score}/100 | ${d.weight}% | ${(d.confidence * 100).toFixed(0)}% |`);
+        }
+    }
+    return lines.join("\n");
+}
+function formatCompareAreas(results) {
+    if (results === null)
+        return "Comparison could not be resolved.";
+    const r = results;
+    const lines = [];
+    lines.push(`**Scope:** ${r.meta.scope}`);
+    lines.push("");
+    for (const slot of r.areas) {
+        lines.push(`### ${slot.query}`);
+        if (slot.profile === null) {
+            lines.push("Could not resolve.");
+        }
+        else {
+            lines.push(formatAreaProfileAsText(slot.profile));
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+function formatFindPeersFromQuery(results) {
+    if (results === null)
+        return "Peers could not be resolved.";
+    const r = results;
+    return renderPeersBlock(r);
+}
+function formatFindInsights(results) {
+    if (results === null)
+        return "Insights could not be computed.";
+    const r = results;
+    const lines = [];
+    lines.push(`**Signal:** ${r.signal_key}`);
+    lines.push(`**Scope:** ${r.meta.scope}`);
+    if (r.meta.threshold !== null)
+        lines.push(`**Threshold:** |z| >= ${r.meta.threshold}`);
+    lines.push("");
+    if (r.insights.length === 0) {
+        lines.push("No anomalies found.");
+        return lines.join("\n");
+    }
+    lines.push("| Rank | LSOA | peer-relative z | |z| |");
+    lines.push("|---|---|---|---|");
+    let rank = 1;
+    for (const ins of r.insights) {
+        lines.push(`| ${rank} | ${ins.geo_code} | ${ins.peer_relative_z.toFixed(2)} | ${ins.abs_z.toFixed(2)} |`);
+        rank++;
+    }
+    return lines.join("\n");
+}
+function formatFindForecast(results) {
+    if (results === null)
+        return "Forecast could not be computed.";
+    const r = results;
+    const lines = [];
+    lines.push(`**Target:** ${r.target.geo_code}`);
+    lines.push(`**Signal:** ${r.signal_key}`);
+    lines.push(`**Fit:** ${r.meta.n_observations} obs over ${r.meta.window_months}m · slope/month ${r.meta.slope_per_month.toFixed(3)}` +
+        (r.meta.r2 !== null ? ` · R² ${r.meta.r2.toFixed(3)}` : ""));
+    lines.push(`**Latest observed:** ${r.meta.latest_observed_period}`);
+    lines.push("");
+    if (r.points.length === 0) {
+        lines.push("No projection points returned.");
+        return lines.join("\n");
+    }
+    lines.push("| Period | Projected | Lower | Upper |");
+    lines.push("|---|---|---|---|");
+    for (const p of r.points) {
+        lines.push(`| ${p.observed_period} | ${p.projected_value.toFixed(2)} | ${p.lower_bound.toFixed(2)} | ${p.upper_bound.toFixed(2)} |`);
+    }
+    return lines.join("\n");
+}
+/* ── shared ───────────────────────────────────────────────────────── */
+export function renderPeersBlock(r) {
+    const lines = [];
+    lines.push(`**Target LSOA:** ${r.target.geo_code}`);
+    lines.push(`**Scope:** ${r.meta.scope}`);
+    lines.push(`**Comparison signals (${r.target.signals_used.length}):** ${r.target.signals_used.join(", ")}`);
+    lines.push("");
+    if (r.peers.length === 0) {
+        lines.push("No peers found within the requested scope.");
+        return lines.join("\n");
+    }
+    lines.push("| Rank | LSOA | Distance | Signals used |");
+    lines.push("|---|---|---|---|");
+    let rank = 1;
+    for (const p of r.peers) {
+        lines.push(`| ${rank} | ${p.geo_code} | ${p.distance.toFixed(3)} | ${p.n_dims_used} |`);
+        rank++;
+    }
+    return lines.join("\n");
+}
+/* ── entry point ──────────────────────────────────────────────────── */
+export function formatQueryResponseAsText(res) {
+    const op = res.plan.op;
+    const lines = [];
+    lines.push(`# Query result · op: ${op}`);
+    lines.push(`Plan source: ${res.plan_source} · Generated at: ${res.meta.generated_at}`);
+    lines.push("");
+    /* Show the emitted plan params verbatim — transparency about what
+       the planner decided to run. */
+    lines.push(`## Emitted plan`);
+    lines.push("```json");
+    lines.push(JSON.stringify(res.plan, null, 2));
+    lines.push("```");
+    lines.push("");
+    lines.push(`## Results`);
+    switch (op) {
+        case "rank_areas":
+            lines.push(formatRankAreas(res.plan, res.results));
+            break;
+        case "get_area":
+            lines.push(formatGetArea(res.results));
+            break;
+        case "score_area":
+            lines.push(formatScoreArea(res.results));
+            break;
+        case "compare_areas":
+            lines.push(formatCompareAreas(res.results));
+            break;
+        case "find_peers":
+            lines.push(formatFindPeersFromQuery(res.results));
+            break;
+        case "find_insights":
+            lines.push(formatFindInsights(res.results));
+            break;
+        case "find_forecast":
+            lines.push(formatFindForecast(res.results));
+            break;
+    }
+    return lines.join("\n").trimEnd();
+}
+//# sourceMappingURL=intelligence-format.js.map

package/dist/tools/intelligence-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intelligence-format.js","sourceRoot":"","sources":["../../src/tools/intelligence-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAW9D,SAAS,eAAe,CAAC,IAAyB,EAAE,OAAgB;IAClE,MAAM,MAAM,GAAG,IAAI,CAAC,MAOnB,CAAC;IACF,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO;QAC9B,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,MAAM,GAAG;QAC3G,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC;IAE/B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAc,CAAC;IAClE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,mBAAmB,SAAS,EAAE,CAAC,CAAC;IAC3C,IAAI,MAAM,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,IAAI,MAAM,CAAC,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAC3D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC;QAC1F,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,EAAE,CAAC;IACT,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,aAAa,CAAC,OAAgB;IACrC,qDAAqD;IACrD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,6BAA6B,CAAC;IAC3D,OAAO,uBAAuB,CAAC,OAAwD,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,eAAe,CAAC,OAAgB;IACvC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,6BAA6B,CAAC;IAC3D,MAAM,CAAC,GAAG,OAQT,CAAC;IACF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,SAAS,iBAAiB,CAAC,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxI,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC;IAClD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;QAC1D,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACrG,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,mCAAmC,CAAC;IACjE,MAAM,CAAC,GAAG,OAGT,CAAC;IACF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,OAAwD,CAAC,CAAC,CAAC;QACrG,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,wBAAwB,CAAC,OAAgB;IAChD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,8BAA8B,CAAC;IAC5D,MAAM,CAAC,GAAG,OAIT,CAAC;IACF,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,iCAAiC,CAAC;IAC/D,MAAM,CAAC,GAAG,OAIT,CAAC;IACF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACvF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAClC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACtD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,MAAM,GAAG,CAAC,QAAQ,MAAM,GAAG,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1G,IAAI,EAAE,CAAC;IACT,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,iCAAiC,CAAC;IAC/D,MAAM,CAAC,GAAG,OAYT,CAAC;IACF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,cAAc,aAAa,CAAC,CAAC,IAAI,CAAC,aAAa,mBAAmB,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;QACjI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/D,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,IAAI,CAAC,sBAAsB,EAAE,CAAC,CAAC;IACpE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;QAC7C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,eAAe,MAAM,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACvI,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,yEAAyE;AAEzE,MAAM,UAAU,gBAAgB,CAAC,CAIhC;IACC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5G,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;QACzD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IACxD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC;QACxF,IAAI,EAAE,CAAC;IACT,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,yEAAyE;AAEzE,MAAM,UAAU,yBAAyB,CAAC,GAAsB;IAC9D,MAAM,EAAE,GAAe,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;IAEnC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,gBAAgB,GAAG,CAAC,WAAW,oBAAoB,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IACvF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf;qCACiC;IACjC,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC9B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACtB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzB,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,YAAY;YACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACnD,MAAM;QACR,KAAK,UAAU;YACb,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACvC,MAAM;QACR,KAAK,YAAY;YACf,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACzC,MAAM;QACR,KAAK,eAAe;YAClB,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5C,MAAM;QACR,KAAK,YAAY;YACf,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAClD,MAAM;QACR,KAAK,eAAe;YAClB,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5C,MAAM;QACR,KAAK,eAAe;YAClB,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5C,MAAM;IACV,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;AACpC,CAAC"}

package/dist/tools/methodology-for.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP tool: methodology_for
+ *
+ * Returns the methodology explanation for a given scoring dimension. Pure
+ * static lookup — no network call. Source of truth in methodology-data.ts,
+ * which is updated when the engine methodology changes.
+ */
+export declare const methodologyForToolName = "methodology_for";
+export declare const methodologyForToolDef: {
+    readonly name: "methodology_for";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly dimension: {
+                readonly type: "string";
+                readonly description: "Dimension name. Case-insensitive, partial match supported (e.g. 'safety' matches 'Safety & Crime').";
+            };
+        };
+        readonly required: readonly ["dimension"];
+        readonly additionalProperties: false;
+    };
+};
+export interface MethodologyForArgs {
+    dimension: string;
+}
+export declare function parseMethodologyForArgs(raw: unknown): MethodologyForArgs;
+export declare function executeMethodologyFor(args: MethodologyForArgs): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+};

package/dist/tools/methodology-for.js

@@ -0,0 +1,71 @@
+/**
+ * MCP tool: methodology_for
+ *
+ * Returns the methodology explanation for a given scoring dimension. Pure
+ * static lookup — no network call. Source of truth in methodology-data.ts,
+ * which is updated when the engine methodology changes.
+ */
+import { findDimension, METHODOLOGY } from "../methodology-data.js";
+export const methodologyForToolName = "methodology_for";
+export const methodologyForToolDef = {
+    name: methodologyForToolName,
+    description: "Get the methodology explanation for a specific scoring dimension (e.g. 'Safety & Crime', 'Transport', 'Rental Yield'). " +
+        "Returns the data source, summary of how the score is computed, and the per-intent weight. " +
+        "Useful when a customer asks 'why did Safety score 80?' or for procurement teams reviewing methodology before integration. " +
+        `Recognised dimensions: ${METHODOLOGY.map((d) => d.dimension).join(", ")}.`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            dimension: {
+                type: "string",
+                description: "Dimension name. Case-insensitive, partial match supported (e.g. 'safety' matches 'Safety & Crime').",
+            },
+        },
+        required: ["dimension"],
+        additionalProperties: false,
+    },
+};
+export function parseMethodologyForArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("methodology_for arguments must be an object");
+    }
+    const obj = raw;
+    const dimension = obj.dimension;
+    if (typeof dimension !== "string" || dimension.trim().length === 0) {
+        throw new Error("dimension must be a non-empty string");
+    }
+    return { dimension: dimension.trim() };
+}
+export function executeMethodologyFor(args) {
+    const match = findDimension(args.dimension);
+    if (!match) {
+        const available = METHODOLOGY.map((d) => d.dimension).join(", ");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No methodology found for "${args.dimension}". Available dimensions: ${available}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const lines = [];
+    lines.push(`# ${match.dimension}`);
+    lines.push("");
+    lines.push(`**Used in intents:** ${match.intents.join(", ")}`);
+    lines.push(`**Data source:** ${match.source}`);
+    lines.push("");
+    lines.push(`## How it scores`);
+    lines.push(match.summary);
+    lines.push("");
+    lines.push(`## Weight per intent`);
+    for (const [intent, weight] of Object.entries(match.weights)) {
+        if (weight > 0)
+            lines.push(`- **${intent}**: ${weight}%`);
+    }
+    lines.push("");
+    lines.push(`Full methodology: https://www.onegoodarea.com/methodology`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+}
+//# sourceMappingURL=methodology-for.js.map

package/dist/tools/methodology-for.js.map

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

package/dist/tools/score-postcode.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP tool: score_postcode
+ *
+ * Lets a Claude / Cursor / MCP-compatible client score any UK area for a
+ * given decision preset. Wraps POST /v1/score?explain=true so the response
+ * carries server-side composed summary + per-dimension reasoning +
+ * recommendations + data-source attribution. The MCP NEVER synthesises
+ * narrative — every line of output comes from real engine state.
+ */
+import type { OogaApiClient, Preset, OogaScoreResponse } from "../api-client.js";
+export declare const scorePostcodeToolName = "score_postcode";
+export declare const scorePostcodeToolDef: {
+    readonly name: "score_postcode";
+    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 preset: {
+                readonly type: "string";
+                readonly enum: readonly ["moving", "business", "investing", "research"];
+                readonly description: string;
+            };
+        };
+        readonly required: readonly ["area", "preset"];
+        readonly additionalProperties: false;
+    };
+};
+export interface ScorePostcodeArgs {
+    area: string;
+    preset: Preset;
+}
+export declare function parseScorePostcodeArgs(raw: unknown): ScorePostcodeArgs;
+export declare function formatScoreResultAsText(result: OogaScoreResponse): string;
+/**
+ * Tool execution. Calls the API, returns formatted text. Throws on auth /
+ * quota errors with a clear message the LLM can pass to the user.
+ */
+export declare function executeScorePostcode(client: OogaApiClient, args: ScorePostcodeArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/score-postcode.js

@@ -0,0 +1,108 @@
+/**
+ * MCP tool: score_postcode
+ *
+ * Lets a Claude / Cursor / MCP-compatible client score any UK area for a
+ * given decision preset. Wraps POST /v1/score?explain=true so the response
+ * carries server-side composed summary + per-dimension reasoning +
+ * recommendations + data-source attribution. The MCP NEVER synthesises
+ * narrative — every line of output comes from real engine state.
+ */
+import { OogaApiError } from "../api-client.js";
+export const scorePostcodeToolName = "score_postcode";
+export const scorePostcodeToolDef = {
+    name: scorePostcodeToolName,
+    description: "Score a UK postcode (or place name) for a given decision preset using the OneGoodArea engine. " +
+        "Returns the overall 0-100 score, five weighted dimensions with confidence + engine-grounded reasoning, " +
+        "a server-composed one-paragraph summary, actionable recommendations from low-scoring or low-confidence dimensions, " +
+        "and the list of public datasets that contributed. Every value is deterministic; the engine version is stamped on every response.",
+    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.",
+            },
+            preset: {
+                type: "string",
+                enum: ["moving", "business", "investing", "research"],
+                description: "Decision context. 'moving' = origination scoring (residential mortgage suitability, demand-side risk). " +
+                    "'business' = site selection (footfall, competition, commercial viability). " +
+                    "'investing' = investment scoring (yield, growth, regeneration). " +
+                    "'research' = reference scoring (neutral baseline across all five dimensions).",
+            },
+        },
+        required: ["area", "preset"],
+        additionalProperties: false,
+    },
+};
+export function parseScorePostcodeArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("score_postcode arguments must be an object");
+    }
+    const obj = raw;
+    const area = obj.area;
+    const preset = obj.preset;
+    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");
+    }
+    const presets = ["moving", "business", "investing", "research"];
+    if (typeof preset !== "string" || !presets.includes(preset)) {
+        throw new Error(`preset must be one of: ${presets.join(", ")}`);
+    }
+    return { area: area.trim(), preset: preset };
+}
+export function formatScoreResultAsText(result) {
+    const lines = [];
+    lines.push(`# ${result.area} · ${result.preset} · ${result.score}/100`);
+    lines.push(`Engine version: ${result.engine_version}`);
+    lines.push(`Area type: ${result.area_type}`);
+    lines.push("");
+    if (result.summary) {
+        lines.push(`## Summary`);
+        lines.push(result.summary);
+        lines.push("");
+    }
+    lines.push(`## Dimensions`);
+    for (const d of result.dimensions) {
+        const conf = ` · confidence ${(d.confidence * 100).toFixed(0)}%`;
+        lines.push(`- **${d.label}**: ${d.score}/100 (weight ${d.weight}%${conf})`);
+        lines.push(`  ${d.reasoning}`);
+        lines.push(`  _${d.confidence_reason}_`);
+    }
+    lines.push("");
+    if (result.recommendations && result.recommendations.length > 0) {
+        lines.push(`## Recommendations`);
+        for (const r of result.recommendations)
+            lines.push(`- ${r}`);
+        lines.push("");
+    }
+    if (result.data_sources && result.data_sources.length > 0) {
+        lines.push(`## Data sources`);
+        lines.push(result.data_sources.join(" · "));
+    }
+    return lines.join("\n").trimEnd();
+}
+/**
+ * Tool execution. Calls the API, returns formatted text. Throws on auth /
+ * quota errors with a clear message the LLM can pass to the user.
+ */
+export async function executeScorePostcode(client, args) {
+    try {
+        const result = await client.scoreArea(args.area, args.preset);
+        return {
+            content: [{ type: "text", text: formatScoreResultAsText(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=score-postcode.js.map

package/dist/tools/score-postcode.js.map

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

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

@@ -0,0 +1,11 @@
+/**
+ * Shared markdown formatter for the Signals tools (AR-366).
+ *
+ * Both `get_area_signals` and `get_signals_by_category` return the same
+ * AreaProfile shape; this module renders it consistently. Every line is
+ * a real field from the response — no client-side text synthesis.
+ */
+import type { OogaAreaProfile, SignalCategory } from "../api-client.js";
+/** Format an AreaProfile as a markdown brief. If `restrictTo` is given,
+    only that category renders (used by get_signals_by_category). */
+export declare function formatAreaProfileAsText(profile: OogaAreaProfile, restrictTo?: SignalCategory): string;

package/dist/tools/signals-format.js

@@ -0,0 +1,116 @@
+/**
+ * Shared markdown formatter for the Signals tools (AR-366).
+ *
+ * Both `get_area_signals` and `get_signals_by_category` return the same
+ * AreaProfile shape; this module renders it consistently. Every line is
+ * a real field from the response — no client-side text synthesis.
+ */
+/** Format a Signal value for display. Numbers get optional comma thousands
+    separators when they're large; strings render verbatim; null → "—". */
+function formatValue(s) {
+    if (s.value === null)
+        return "—";
+    if (typeof s.value === "string")
+        return s.value;
+    const n = s.value;
+    /* Currency: render as £42,500 with no decimals. */
+    if (s.unit === "GBP")
+        return `£${Math.round(n).toLocaleString("en-GB")}`;
+    /* Percent: render with one decimal + suffix. */
+    if (s.unit === "pct")
+        return `${n.toFixed(1)}%`;
+    /* Integer-like units. */
+    if (s.unit === "count" || s.unit === "rank" || s.unit === "decile") {
+        return Math.round(n).toLocaleString("en-GB");
+    }
+    /* Per-period. */
+    if (s.unit === "per_month")
+        return `${n.toFixed(1)} / mo`;
+    /* Default: number as-is. */
+    return n.toLocaleString("en-GB");
+}
+function formatPercentile(p) {
+    /* Use one decimal only when the value would otherwise round away. */
+    if (p === Math.round(p))
+        return `${p}th percentile`;
+    return `${p.toFixed(1)}th percentile`;
+}
+function renderSignal(s) {
+    const lines = [];
+    const unit = s.unit ? ` ${s.unit}` : "";
+    const valueLine = `**${s.label}**: ${formatValue(s)}${s.value !== null && s.unit && !["GBP", "pct"].includes(s.unit) ? unit : ""}`;
+    lines.push(`- ${valueLine}`);
+    /* Percentile (store-backed only). */
+    if (typeof s.percentile === "number") {
+        lines.push(`  ${formatPercentile(s.percentile)} (direction: ${s.direction.replace(/_/g, " ")})`);
+    }
+    /* Confidence with engine-grounded reason. */
+    lines.push(`  Confidence ${(s.confidence * 100).toFixed(0)}% · ${s.confidence_reason}`);
+    /* Provenance. */
+    lines.push(`  Source: ${s.source} · ${s.observed_period}`);
+    return lines;
+}
+/** Format an AreaProfile as a markdown brief. If `restrictTo` is given,
+    only that category renders (used by get_signals_by_category). */
+export function formatAreaProfileAsText(profile, restrictTo) {
+    const lines = [];
+    const geo = profile.geo;
+    /* Headline. */
+    const headlineParts = [geo.query];
+    if (geo.postcode && geo.postcode !== geo.query)
+        headlineParts.push(`(${geo.postcode})`);
+    if (restrictTo)
+        headlineParts.push(`— ${restrictTo}`);
+    lines.push(`# ${headlineParts.join(" ")}`);
+    lines.push(`Engine version: ${profile.meta.engine_version} · Fetch mode: ${profile.meta.fetch_mode}`);
+    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("");
+    /* Group signals by category (preserves category order from the data
+       since /v1/area returns them in that order; filter() preserves order). */
+    const signals = restrictTo
+        ? profile.signals.filter((s) => s.category === restrictTo)
+        : profile.signals;
+    if (signals.length === 0) {
+        lines.push(restrictTo
+            ? `No ${restrictTo} signals returned for this area.`
+            : "No signals returned for this area.");
+        return lines.join("\n").trimEnd();
+    }
+    const byCategory = new Map();
+    for (const s of signals) {
+        const cat = s.category;
+        if (!byCategory.has(cat))
+            byCategory.set(cat, []);
+        byCategory.get(cat).push(s);
+    }
+    /* Category header per group when not restricted; just one flat list
+       when restricted (the category is already in the document title). */
+    for (const [category, group] of byCategory) {
+        if (!restrictTo) {
+            lines.push(`## ${category}`);
+        }
+        for (const s of group) {
+            for (const line of renderSignal(s))
+                lines.push(line);
+        }
+        lines.push("");
+    }
+    /* Sources footer (deduplicated, from the response meta). */
+    if (profile.meta.sources.length > 0) {
+        lines.push(`## Data sources`);
+        lines.push(profile.meta.sources.join(" · "));
+    }
+    return lines.join("\n").trimEnd();
+}
+//# sourceMappingURL=signals-format.js.map

package/dist/tools/signals-format.js.map

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