@oga-mcp/server 1.0.0

package/dist/tools/watch-portfolio.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MCP tool: watch_portfolio (AR-368)
+ *
+ * One-shot setup for a Monitor portfolio: creates the portfolio and adds
+ * the tracked areas in a single call so the LLM can set up watching
+ * conversationally. Wraps POST /v1/portfolios + POST /v1/portfolios/:id/areas
+ * sequentially.
+ *
+ * Failure handling: if the create succeeds but the add fails, the response
+ * still surfaces the new portfolio_id with `areas_added: 0` so the LLM can
+ * tell the user "the portfolio exists but no areas were added; retry with..."
+ */
+import type { OogaApiClient } from "../api-client.js";
+export declare const watchPortfolioToolName = "watch_portfolio";
+export declare const watchPortfolioToolDef: {
+    readonly name: "watch_portfolio";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly description: "Display name for the portfolio. 1-200 characters.";
+            };
+            readonly areas: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly minItems: 1;
+                readonly maxItems: 100;
+                readonly description: "UK postcodes or place names to track. 1-100 entries.";
+            };
+        };
+        readonly required: readonly ["name", "areas"];
+        readonly additionalProperties: false;
+    };
+};
+export interface WatchPortfolioArgs {
+    name: string;
+    areas: string[];
+}
+export declare function parseWatchPortfolioArgs(raw: unknown): WatchPortfolioArgs;
+export declare function executeWatchPortfolio(client: OogaApiClient, args: WatchPortfolioArgs): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/watch-portfolio.js

@@ -0,0 +1,126 @@
+/**
+ * MCP tool: watch_portfolio (AR-368)
+ *
+ * One-shot setup for a Monitor portfolio: creates the portfolio and adds
+ * the tracked areas in a single call so the LLM can set up watching
+ * conversationally. Wraps POST /v1/portfolios + POST /v1/portfolios/:id/areas
+ * sequentially.
+ *
+ * Failure handling: if the create succeeds but the add fails, the response
+ * still surfaces the new portfolio_id with `areas_added: 0` so the LLM can
+ * tell the user "the portfolio exists but no areas were added; retry with..."
+ */
+import { OogaApiError } from "../api-client.js";
+export const watchPortfolioToolName = "watch_portfolio";
+const MAX_AREAS_PER_CALL = 100;
+export const watchPortfolioToolDef = {
+    name: watchPortfolioToolName,
+    description: "Set up a Monitor portfolio in one step: creates a named portfolio and adds tracked UK areas. " +
+        "Use this when the LLM is helping a user watch a list of postcodes or place names over time. " +
+        "After this succeeds, use get_portfolio_changes(portfolio_id) to check for material signal moves between periods.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "Display name for the portfolio. 1-200 characters.",
+            },
+            areas: {
+                type: "array",
+                items: { type: "string" },
+                minItems: 1,
+                maxItems: MAX_AREAS_PER_CALL,
+                description: `UK postcodes or place names to track. 1-${MAX_AREAS_PER_CALL} entries.`,
+            },
+        },
+        required: ["name", "areas"],
+        additionalProperties: false,
+    },
+};
+export function parseWatchPortfolioArgs(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("watch_portfolio arguments must be an object");
+    }
+    const obj = raw;
+    const name = obj.name;
+    const areas = obj.areas;
+    if (typeof name !== "string" || name.trim().length === 0) {
+        throw new Error("name must be a non-empty string");
+    }
+    if (name.length > 200) {
+        throw new Error("name must be 200 characters or fewer");
+    }
+    if (!Array.isArray(areas) || areas.length === 0) {
+        throw new Error("areas must be a non-empty array");
+    }
+    if (areas.length > MAX_AREAS_PER_CALL) {
+        throw new Error(`areas must contain at most ${MAX_AREAS_PER_CALL} 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());
+    }
+    return { name: name.trim(), areas: cleaned };
+}
+function formatPortfolioSetup(created, added, addError) {
+    const lines = [];
+    lines.push(`# Portfolio: ${created.name}`);
+    lines.push(`**ID:** \`${created.id}\``);
+    if (created.created_at)
+        lines.push(`**Created:** ${created.created_at}`);
+    lines.push("");
+    if (added !== null) {
+        lines.push(`**Areas tracked (${added.areas.length}):**`);
+        for (const a of added.areas) {
+            const label = a.label ? ` — ${a.label}` : "";
+            lines.push(`- ${a.area}${label}`);
+        }
+        lines.push("");
+        lines.push(`Use \`get_portfolio_changes\` with portfolio_id \`${created.id}\` to check for material signal moves.`);
+    }
+    else {
+        lines.push("**Areas tracked: 0**");
+        lines.push("");
+        lines.push(`The portfolio was created but the area-add step failed: ${addError ?? "unknown error"}.`);
+        lines.push(`Retry by calling watch_portfolio with the same name and the same areas (the duplicate portfolio is harmless to leave; or delete it via the dashboard).`);
+    }
+    return lines.join("\n").trimEnd();
+}
+export async function executeWatchPortfolio(client, args) {
+    let created;
+    try {
+        created = await client.createPortfolio(args.name);
+    }
+    catch (err) {
+        if (err instanceof OogaApiError) {
+            const msg = `OneGoodArea API error (HTTP ${err.status ?? "?"}) creating portfolio: ${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 };
+    }
+    /* Phase 2 — add areas. If it fails, the portfolio exists empty; surface
+       that so the LLM can act rather than swallowing the create. */
+    try {
+        const added = await client.addPortfolioAreas(created.id, args.areas.map((a) => ({ area: a })));
+        return { content: [{ type: "text", text: formatPortfolioSetup(created, added, null) }] };
+    }
+    catch (err) {
+        const msg = err instanceof OogaApiError
+            ? `HTTP ${err.status ?? "?"}: ${err.message}`
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return {
+            content: [{ type: "text", text: formatPortfolioSetup(created, null, msg) }],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=watch-portfolio.js.map

package/dist/tools/watch-portfolio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-portfolio.js","sourceRoot":"","sources":["../../src/tools/watch-portfolio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AAExD,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,sBAAsB;IAC5B,WAAW,EACT,+FAA+F;QAC/F,8FAA8F;QAC9F,kHAAkH;IACpH,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,mDAAmD;aACjE;YACD,KAAK,EAAE;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,kBAAkB;gBAC5B,WAAW,EAAE,2CAA2C,kBAAkB,WAAW;aACtF;SACF;QACD,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QAC3B,oBAAoB,EAAE,KAAK;KAC5B;CACO,CAAC;AAOX,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IAExB,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,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,8BAA8B,kBAAkB,UAAU,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED,SAAS,oBAAoB,CAC3B,OAAsB,EACtB,KAAiC,EACjC,QAAuB;IAEvB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IACxC,IAAI,OAAO,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACzE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,oBAAoB,KAAK,CAAC,KAAK,CAAC,MAAM,MAAM,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,qDAAqD,OAAO,CAAC,EAAE,wCAAwC,CAAC,CAAC;IACtH,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,2DAA2D,QAAQ,IAAI,eAAe,GAAG,CAAC,CAAC;QACtG,KAAK,CAAC,IAAI,CAAC,wJAAwJ,CAAC,CAAC;IACvK,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAqB,EACrB,IAAwB;IAExB,IAAI,OAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,+BAA+B,GAAG,CAAC,MAAM,IAAI,GAAG,yBAAyB,GAAG,CAAC,OAAO,EAAE,CAAC;YACnG,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;IAED;oEACgE;IAChE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAC1C,OAAO,CAAC,EAAE,EACV,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CACrC,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IAC3F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,YAAY;YACrC,CAAC,CAAC,QAAQ,GAAG,CAAC,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,OAAO,EAAE;YAC7C,CAAC,CAAC,GAAG,YAAY,KAAK;gBACpB,CAAC,CAAC,GAAG,CAAC,OAAO;gBACb,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClB,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAC3E,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@oga-mcp/server",
+  "version": "1.0.0",
+  "description": "MCP server for OneGoodArea — UK area intelligence inside Claude Desktop, Cursor, and any MCP-compatible client. Returns server-composed briefs (summary + per-dimension reasoning + confidence + data sources) from the deterministic engine.",
+  "license": "MIT",
+  "homepage": "https://www.onegoodarea.com/docs/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneGoodArea/OneGoodArea.git",
+    "directory": "mcp"
+  },
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "oga-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/server.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "onegoodarea",
+    "uk",
+    "location-intelligence",
+    "property",
+    "postcode"
+  ]
+}