@rubytech/create-maxy-code 0.1.58 → 0.1.60

package/payload/platform/plugins/property-data/mcp/src/__tests__/endpoints.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Task 144 — per-endpoint coverage for the 10 new PropertyData adapters.
+ * For each new endpoint, assert:
+ *   1. happy path — JSON parses and round-trips through the adapter
+ *   2. 4xx upstream → PropertyDataError with status preserved
+ *   3. non-JSON body → BadResponseError
+ *   4. missing key → KeyNotRegisteredError
+ *
+ * The existing propertydata-api.test.ts proves the four paths fire from
+ * `propertyDataCall`; this file proves each of the 10 adapter exports
+ * threads its own endpoint path through that same plumbing so the
+ * MCP tool actually hits the right URL.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock the Neo4j layer keyed by accountId so each test can choose an
+// already-registered account (happy / 4xx / bad-response) or a brand-new
+// "ghost" account (missing-key) without ordering coupling.
+vi.mock("../lib/neo4j.js", () => {
+  const stored = new Map<string, string>();
+  return {
+    getSession: () => ({
+      run: vi.fn(async (cypher: string, params: Record<string, unknown>) => {
+        const accountId = String(params.accountId ?? "");
+        if (/MATCH \(k:PropertyDataKey/.test(cypher) && /RETURN/.test(cypher)) {
+          const encryptedKey = stored.get(accountId);
+          return {
+            records: encryptedKey
+              ? [
+                  {
+                    get: (k: string) => {
+                      if (k === "encryptedKey") return encryptedKey;
+                      if (k === "createdAt") return "2026-01-01T00:00:00Z";
+                      if (k === "updatedAt") return "2026-01-01T00:00:00Z";
+                      return null;
+                    },
+                  },
+                ]
+              : [],
+          };
+        }
+        if (/MERGE \(k:PropertyDataKey/.test(cypher)) {
+          stored.set(accountId, String(params.encryptedKey));
+          return { records: [] };
+        }
+        if (/DELETE k/.test(cypher)) {
+          const had = stored.delete(accountId);
+          return {
+            records: [
+              {
+                get: (k: string) =>
+                  k === "deleted" ? { toNumber: () => (had ? 1 : 0) } : null,
+              },
+            ],
+          };
+        }
+        return { records: [] };
+      }),
+      close: vi.fn(async () => {}),
+    }),
+    closeDriver: vi.fn(async () => {}),
+  };
+});
+
+vi.mock("../lib/crypto.js", () => ({
+  encrypt: (s: string) => `enc:${s}`,
+  decrypt: (s: string) => s.replace(/^enc:/, ""),
+}));
+
+import {
+  pricesPerSqf,
+  soldPricesPerSqf,
+  crime,
+  floodRisk,
+  councilTax,
+  planningApplications,
+  addressMatchUprn,
+  growthPsf,
+  demandRent,
+  propertyTypes,
+} from "../tools/endpoints.js";
+import {
+  KeyNotRegisteredError,
+  PropertyDataError,
+  BadResponseError,
+} from "../lib/propertydata-api.js";
+import { keyRegister } from "../tools/key-register.js";
+
+const originalFetch = globalThis.fetch;
+
+function mockFetch(impl: (url: string) => Response | Promise<Response>) {
+  const fn = vi.fn(async (url: string | URL | Request) => impl(String(url))) as unknown as typeof fetch;
+  globalThis.fetch = fn;
+  return fn as unknown as ReturnType<typeof vi.fn>;
+}
+
+async function registerTestKey(accountId: string) {
+  mockFetch(() => new Response(JSON.stringify({ status: "success", uk_hpi: 100 }), { status: 200 }));
+  await keyRegister({ apiKey: "test-key-12345", accountId });
+}
+
+beforeEach(() => {
+  // no-op
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+interface EndpointCase {
+  toolName: string;
+  endpointPath: string;
+  adapter: (args: { accountId: string } & Record<string, unknown>) => Promise<string>;
+  sampleParams: Record<string, unknown>;
+  happyPayload: Record<string, unknown>;
+  happyAssertField: string;
+}
+
+const cases: EndpointCase[] = [
+  {
+    toolName: "property-data-prices-per-sqf",
+    endpointPath: "prices-per-sqf",
+    adapter: pricesPerSqf,
+    sampleParams: { postcode: "CM23 2UJ" },
+    happyPayload: { status: "success", data: { avg: 450 } },
+    happyAssertField: "avg",
+  },
+  {
+    toolName: "property-data-sold-prices-per-sqf",
+    endpointPath: "sold-prices-per-sqf",
+    adapter: soldPricesPerSqf,
+    sampleParams: { postcode: "CM23 2UJ", max_age: 24 },
+    happyPayload: { status: "success", data: { avg: 425, sales: [] } },
+    happyAssertField: "avg",
+  },
+  {
+    toolName: "property-data-crime",
+    endpointPath: "crime",
+    adapter: crime,
+    sampleParams: { postcode: "CM23" },
+    happyPayload: { status: "success", data: { rate_per_1000: 42 } },
+    happyAssertField: "rate_per_1000",
+  },
+  {
+    toolName: "property-data-flood-risk",
+    endpointPath: "flood-risk",
+    adapter: floodRisk,
+    sampleParams: { postcode: "CM23 2UJ" },
+    happyPayload: { status: "success", data: { river: "very-low" } },
+    happyAssertField: "river",
+  },
+  {
+    toolName: "property-data-council-tax",
+    endpointPath: "council-tax",
+    adapter: councilTax,
+    sampleParams: { postcode: "CM23 2UJ" },
+    happyPayload: { status: "success", data: { council: "East Herts", band_d: 2100 } },
+    happyAssertField: "council",
+  },
+  {
+    toolName: "property-data-planning-applications",
+    endpointPath: "planning-applications",
+    adapter: planningApplications,
+    sampleParams: { postcode: "CM23", results: 10 },
+    happyPayload: { status: "success", data: { applications: [] } },
+    happyAssertField: "applications",
+  },
+  {
+    toolName: "property-data-address-match-uprn",
+    endpointPath: "address-match-uprn",
+    adapter: addressMatchUprn,
+    sampleParams: { address: "1 The High Street, Bishop's Stortford, CM23 2UJ" },
+    happyPayload: { status: "success", data: { uprn: "10001234567" } },
+    happyAssertField: "uprn",
+  },
+  {
+    toolName: "property-data-growth-psf",
+    endpointPath: "growth-psf",
+    adapter: growthPsf,
+    sampleParams: { postcode: "CM23" },
+    happyPayload: { status: "success", data: { series: [{ year: 2019, psf: 400 }] } },
+    happyAssertField: "series",
+  },
+  {
+    toolName: "property-data-demand-rent",
+    endpointPath: "demand-rent",
+    adapter: demandRent,
+    sampleParams: { postcode: "CM23", bedrooms: 3 },
+    happyPayload: { status: "success", data: { for_rent: 12, lets_per_month: 4 } },
+    happyAssertField: "for_rent",
+  },
+  {
+    toolName: "property-data-property-types",
+    endpointPath: "property-types",
+    adapter: propertyTypes,
+    sampleParams: { postcode: "CM23" },
+    happyPayload: { status: "success", data: { detached: 28, flat: 12 } },
+    happyAssertField: "detached",
+  },
+];
+
+describe("Task 144 endpoint adapters", () => {
+  for (const c of cases) {
+    describe(c.toolName, () => {
+      const acct = `acct-${c.endpointPath}`;
+
+      it("happy path returns the parsed JSON payload", async () => {
+        await registerTestKey(acct);
+        let capturedUrl = "";
+        mockFetch((url) => {
+          capturedUrl = url;
+          return new Response(JSON.stringify(c.happyPayload), { status: 200 });
+        });
+        const text = await c.adapter({ accountId: acct, ...c.sampleParams });
+        expect(capturedUrl).toContain(`/${c.endpointPath}?`);
+        const parsed = JSON.parse(text);
+        // payload has shape { status, data: { ... } } — assert the field
+        // exists somewhere in the round-tripped output.
+        expect(JSON.stringify(parsed)).toContain(c.happyAssertField);
+      });
+
+      it("maps HTTP 4xx to PropertyDataError preserving the status", async () => {
+        await registerTestKey(acct);
+        mockFetch(() => new Response("bad request", { status: 400 }));
+        try {
+          await c.adapter({ accountId: acct, ...c.sampleParams });
+          throw new Error("expected PropertyDataError");
+        } catch (err) {
+          expect(err).toBeInstanceOf(PropertyDataError);
+          expect((err as PropertyDataError).status).toBe(400);
+        }
+      });
+
+      it("maps non-JSON body to BadResponseError", async () => {
+        await registerTestKey(acct);
+        mockFetch(() => new Response("<html>maintenance</html>", { status: 200 }));
+        await expect(
+          c.adapter({ accountId: acct, ...c.sampleParams }),
+        ).rejects.toBeInstanceOf(BadResponseError);
+      });
+
+      it("throws KeyNotRegisteredError when no key is stored", async () => {
+        // brand-new account with nothing registered
+        await expect(
+          c.adapter({ accountId: `${acct}-ghost`, ...c.sampleParams }),
+        ).rejects.toBeInstanceOf(KeyNotRegisteredError);
+      });
+    });
+  }
+});

package/payload/platform/plugins/property-data/mcp/src/__tests__/schema-parity.test.ts

@@ -38,11 +38,25 @@ describe("schema parity", () => {
     expect(registered).toEqual(declared);
   });
 
-  it("declares all 12 tools (3 key-mgmt + 9 endpoints)", () => {
+  it("declares all 22 tools (3 key-mgmt + 19 endpoints)", () => {
     const declared = readPluginMdTools();
-    expect(declared).toHaveLength(12);
+    expect(declared).toHaveLength(22);
     expect(declared).toContain("property-data-key-register");
     expect(declared).toContain("property-data-valuation-sale");
     expect(declared).toContain("property-data-national-hpi");
+    for (const name of [
+      "property-data-prices-per-sqf",
+      "property-data-sold-prices-per-sqf",
+      "property-data-crime",
+      "property-data-flood-risk",
+      "property-data-council-tax",
+      "property-data-planning-applications",
+      "property-data-address-match-uprn",
+      "property-data-growth-psf",
+      "property-data-demand-rent",
+      "property-data-property-types",
+    ]) {
+      expect(declared).toContain(name);
+    }
   });
 });

package/payload/platform/plugins/property-data/mcp/src/index.ts

@@ -1,5 +1,6 @@
-import { initStderrTee } from "../../../../../../platform/lib/mcp-stderr-tee/dist/index.js";
-initStderrTee("property-data");
+// Logging-tee was a platform-wrapper concern: the platform's mcp-spawn-tee
+// pipes our stderr where it wants. In standalone mode (Claude Code native
+// spawn) the host owns the stderr pipe. Either way, we just write to stderr.
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -17,6 +18,16 @@ import {
   yields,
   growth,
   nationalHpi,
+  pricesPerSqf,
+  soldPricesPerSqf,
+  crime,
+  floodRisk,
+  councilTax,
+  planningApplications,
+  addressMatchUprn,
+  growthPsf,
+  demandRent,
+  propertyTypes,
 } from "./tools/endpoints.js";
 import { closeDriver } from "./lib/neo4j.js";
 import {
@@ -24,18 +35,22 @@ import {
   PropertyDataError,
   BadResponseError,
 } from "./lib/propertydata-api.js";
+import { selectKeyStore } from "./lib/key-store.js";
 
-const accountId = process.env.ACCOUNT_ID;
-if (!accountId) {
-  throw new Error("ACCOUNT_ID environment variable is required");
-}
+// ACCOUNT_ID is the platform's tenant id; in standalone mode (Claude Code
+// native spawn) there is no platform tenant, so "local" is the single-tenant
+// stand-in. Same MCP body, env-selected backend.
+const accountId = process.env.ACCOUNT_ID ?? "local";
 
 const server = new McpServer({
   name: "maxy-property-data",
   version: "0.1.0",
 });
 
-console.error(`[property-data] server started, account=${accountId}`);
+const store = selectKeyStore();
+console.error(
+  `[property-data] server started, account=${accountId} backend=${store.backendName} path=${store.backendPath}`,
+);
 
 function errorEnvelope(err: unknown): { content: { type: "text"; text: string }[]; isError: true } {
   let text: string;
@@ -57,7 +72,7 @@ function endpointHandler<P extends Record<string, unknown>>(
 ) {
   return async (params: P) => {
     try {
-      const text = await fn({ ...params, accountId: accountId as string });
+      const text = await fn({ ...params, accountId });
       return { content: [{ type: "text" as const, text }] };
     } catch (err) {
       return errorEnvelope(err);
@@ -77,7 +92,7 @@ server.tool(
   },
   async ({ apiKey }) => {
     try {
-      await keyRegister({ apiKey, accountId: accountId as string });
+      await keyRegister({ apiKey, accountId });
       return {
         content: [
           {
@@ -98,7 +113,7 @@ server.tool(
   {},
   async () => {
     try {
-      await keyDeregister({ accountId: accountId as string });
+      await keyDeregister({ accountId });
       return {
         content: [{ type: "text" as const, text: "PropertyData API key deregistered." }],
       };
@@ -114,7 +129,7 @@ server.tool(
   {},
   async () => {
     try {
-      const text = await keyList({ accountId: accountId as string });
+      const text = await keyList({ accountId });
       return { content: [{ type: "text" as const, text }] };
     } catch (err) {
       return errorEnvelope(err);
@@ -236,6 +251,151 @@ server.tool(
   endpointHandler(nationalHpi),
 );
 
+// ─────────────────────────────────────────────────────────────────
+// Task 144 — £/sqft baselines and growth
+// ─────────────────────────────────────────────────────────────────
+
+const pricesPerSqfSchema = {
+  postcode: z.string().min(2).describe("UK postcode (outcode or full)"),
+  type: z
+    .enum(["detached", "semi-detached", "terraced", "flat"])
+    .optional()
+    .describe("Filter by property type"),
+  bedrooms: z.number().int().min(0).optional().describe("Filter by bedroom count"),
+};
+
+server.tool(
+  "property-data-prices-per-sqf",
+  "Asking £/sqft distribution for sale listings in a postcode — avg plus 70/80/90/100% percentile ranges, with the raw listings that have square-foot data. Use for the asking £/sqft KPI on a market report. Costs 1 credit per call.",
+  pricesPerSqfSchema,
+  endpointHandler(pricesPerSqf),
+);
+
+server.tool(
+  "property-data-sold-prices-per-sqf",
+  "Land Registry sold £/sqft distribution for a postcode — avg plus percentile ranges, up to 20 raw sales with square-foot data and a sales-window date range. Use for the achieved £/sqft KPI. Costs 1 credit per call.",
+  {
+    postcode: z.string().min(2).describe("UK postcode (outcode or full)"),
+    type: z
+      .enum(["detached", "semi-detached", "terraced", "flat"])
+      .optional()
+      .describe("Filter by property type"),
+    bedrooms: z.number().int().min(0).optional().describe("Filter by bedroom count"),
+    max_age: z.number().int().min(1).optional().describe("Max transaction age in months"),
+  },
+  endpointHandler(soldPricesPerSqf),
+);
+
+server.tool(
+  "property-data-growth-psf",
+  "7-year £/sqft series with year-on-year percent change for a postcode. Use for the £/sqft growth chart on a market report. Costs 1 credit per call.",
+  {
+    postcode: z.string().min(2).describe("UK postcode (outcode or full)"),
+    type: z
+      .enum(["detached", "semi-detached", "terraced", "flat"])
+      .optional()
+      .describe("Filter by property type"),
+  },
+  endpointHandler(growthPsf),
+);
+
+// ─────────────────────────────────────────────────────────────────
+// Task 144 — Area risk and cost of occupancy
+// ─────────────────────────────────────────────────────────────────
+
+server.tool(
+  "property-data-crime",
+  "Recent crime statistics for a postcode (or location / town) — per-1,000 rate, 12-month total, breakdown by crime type, and per-month observations. Use for the area-risk pillar. Costs 1 credit per call.",
+  {
+    postcode: z.string().min(2).optional().describe("UK postcode (outcode or full)"),
+    location: z
+      .string()
+      .optional()
+      .describe("Latitude,longitude pair (e.g. '51.5074,-0.1278'). Alternative to postcode."),
+    town: z.string().optional().describe("UK town name. Alternative to postcode."),
+  },
+  endpointHandler(crime),
+);
+
+server.tool(
+  "property-data-flood-risk",
+  "River and sea flood-risk rating for a full UK postcode. Use for area-risk reporting and lender-ready disclosures. Requires a full postcode (not outcode). Costs 1 credit per call.",
+  {
+    postcode: z.string().min(5).describe("Full UK postcode (not outcode)"),
+  },
+  endpointHandler(floodRisk),
+);
+
+server.tool(
+  "property-data-council-tax",
+  "Council-tax authority, rating, and per-band charges (A–H) for a full UK postcode, plus any per-property bands the API returns. Use for cost-of-occupancy disclosures. Requires a full postcode. Costs 1 credit per call.",
+  {
+    postcode: z.string().min(5).describe("Full UK postcode (not outcode)"),
+  },
+  endpointHandler(councilTax),
+);
+
+// ─────────────────────────────────────────────────────────────────
+// Task 144 — Planning precedent and address resolution
+// ─────────────────────────────────────────────────────────────────
+
+server.tool(
+  "property-data-planning-applications",
+  "Planning applications within a radius of a postcode — references, proposals, decisions, appeals, distance. Use for development precedent and pre-purchase risk. Costs 2 credits per call. Throttled to ~4 calls per 10 seconds upstream — wrap in the preval skill for fan-out, do not loop directly.",
+  {
+    postcode: z.string().min(2).describe("UK postcode (outcode or full)"),
+    decision_rating: z
+      .enum(["positive", "neutral", "negative"])
+      .optional()
+      .describe("Filter by decision sentiment"),
+    category: z.string().optional().describe("PropertyData planning category filter"),
+    max_age_decision: z
+      .number()
+      .int()
+      .min(1)
+      .optional()
+      .describe("Max age of decision in months"),
+    results: z.number().int().min(1).max(100).optional().describe("Max results to return"),
+  },
+  endpointHandler(planningApplications),
+);
+
+server.tool(
+  "property-data-address-match-uprn",
+  "Resolve a full UK address string to its UPRN, address classification, and lat/lng. Use for CRM hygiene and unique-property identification. Costs 10 credits per call — do not fan out blindly; call once per address you actually need to resolve.",
+  {
+    address: z.string().min(5).describe("Full UK address (line one + postcode)"),
+  },
+  endpointHandler(addressMatchUprn),
+);
+
+// ─────────────────────────────────────────────────────────────────
+// Task 144 — Rental demand and property-type mix
+// ─────────────────────────────────────────────────────────────────
+
+server.tool(
+  "property-data-demand-rent",
+  "Rental demand signals for a postcode — for-rent count, lets per month, turnover percent, months of inventory, days on market, and a rating. Use for the rental pillar on a market report. Costs 1 credit per call.",
+  {
+    postcode: z.string().min(2).describe("UK postcode (outcode or full)"),
+    bedrooms: z.number().int().min(0).optional().describe("Filter by bedroom count"),
+    type: z
+      .enum(["detached", "semi-detached", "terraced", "flat"])
+      .optional()
+      .describe("Filter by property type"),
+  },
+  endpointHandler(demandRent),
+);
+
+server.tool(
+  "property-data-property-types",
+  "Output-area property-type distribution (percent by class — detached, semi-detached, terraced, flat) for a postcode. Use for the property-type mix doughnut on a market report. Costs 1 credit per call.",
+  {
+    postcode: z.string().min(2).describe("UK postcode (outcode or full)"),
+  },
+  endpointHandler(propertyTypes),
+);
+
 // ─────────────────────────────────────────────────────────────────
 // Lifecycle
 // ─────────────────────────────────────────────────────────────────

package/payload/platform/plugins/property-data/mcp/src/lib/file-crypto.ts

@@ -0,0 +1,55 @@
+import { randomBytes, createCipheriv, createDecipheriv } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+
+// Standalone-mode crypto. Same AES-256-GCM envelope as crypto.ts, but the
+// encryption-key file path is passed in (not derived from PLATFORM_ROOT /
+// brand.json), so it can live under ~/.claude/ when the MCP is spawned by
+// Claude Code natively.
+
+const ALGORITHM = "aes-256-gcm";
+const KEY_LENGTH = 32;
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+
+function loadOrGenerateKey(keyFilePath: string, label: string): Buffer {
+  if (existsSync(keyFilePath)) {
+    const hex = readFileSync(keyFilePath, "utf-8").trim();
+    const buf = Buffer.from(hex, "hex");
+    if (buf.length !== KEY_LENGTH) {
+      throw new Error(
+        `[${label}] encryption key at ${keyFilePath} is ${buf.length} bytes, expected ${KEY_LENGTH}.`,
+      );
+    }
+    return buf;
+  }
+  const key = randomBytes(KEY_LENGTH);
+  writeFileSync(keyFilePath, key.toString("hex"), { mode: 0o600 });
+  console.error(`[${label}] encryption key generated at ${keyFilePath}`);
+  return key;
+}
+
+export function encryptWith(plaintext: string, keyFilePath: string, label: string): string {
+  const key = loadOrGenerateKey(keyFilePath, label);
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  let encrypted = cipher.update(plaintext, "utf-8", "hex");
+  encrypted += cipher.final("hex");
+  const authTag = cipher.getAuthTag().toString("hex");
+  return `${iv.toString("hex")}:${encrypted}:${authTag}`;
+}
+
+export function decryptWith(encryptedValue: string, keyFilePath: string, label: string): string {
+  const parts = encryptedValue.split(":");
+  if (parts.length !== 3) {
+    throw new Error(`[${label}] bad encrypted envelope (expected iv:ct:tag)`);
+  }
+  const key = loadOrGenerateKey(keyFilePath, label);
+  const iv = Buffer.from(parts[0], "hex");
+  const ciphertext = parts[1];
+  const authTag = Buffer.from(parts[2], "hex");
+  const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  decipher.setAuthTag(authTag);
+  let plaintext = decipher.update(ciphertext, "hex", "utf-8");
+  plaintext += decipher.final("utf-8");
+  return plaintext;
+}