@sfranalytics/mcp 0.6.0

package/dist/services/snowflake.js

@@ -0,0 +1,71 @@
+import snowflakeSdk from "snowflake-sdk";
+// Disable OCSP check to avoid hanging in some environments
+snowflakeSdk.configure({ ocspFailOpen: true });
+let connection = null;
+let config = null;
+export function initSnowflake(cfg) {
+    config = cfg;
+}
+export function isSnowflakeConfigured() {
+    return config !== null;
+}
+function getConnection() {
+    return new Promise((resolve, reject) => {
+        if (connection && connection.isUp()) {
+            resolve(connection);
+            return;
+        }
+        if (!config) {
+            reject(new Error("Snowflake not configured. Call initSnowflake() first."));
+            return;
+        }
+        const conn = snowflakeSdk.createConnection({
+            account: config.account,
+            username: config.username,
+            password: config.password,
+            database: config.database,
+            schema: config.schema,
+            warehouse: config.warehouse,
+        });
+        conn.connect((err) => {
+            if (err) {
+                reject(new Error(`Snowflake connection failed: ${err.message}`));
+            }
+            else {
+                connection = conn;
+                resolve(conn);
+            }
+        });
+    });
+}
+export async function sfQuery(sql, binds = []) {
+    const conn = await getConnection();
+    return new Promise((resolve, reject) => {
+        conn.execute({
+            sqlText: sql,
+            binds,
+            complete: (err, _stmt, rows) => {
+                if (err) {
+                    reject(new Error(`Snowflake query failed: ${err.message}`));
+                }
+                else {
+                    resolve((rows ?? []));
+                }
+            },
+        });
+    });
+}
+export async function disconnectSnowflake() {
+    if (!connection)
+        return;
+    return new Promise((resolve, reject) => {
+        connection.destroy((err) => {
+            connection = null;
+            if (err)
+                reject(new Error(`Snowflake disconnect failed: ${err.message}`));
+            else
+                resolve();
+        });
+    });
+}
+//# sourceMappingURL=snowflake.js.map

package/dist/services/snowflake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snowflake.js","sourceRoot":"","sources":["../../src/services/snowflake.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAC;AAWzC,2DAA2D;AAC3D,YAAY,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;AAE/C,IAAI,UAAU,GAAmC,IAAI,CAAC;AACtD,IAAI,MAAM,GAA2B,IAAI,CAAC;AAE1C,MAAM,UAAU,aAAa,CAAC,GAAoB;IAChD,MAAM,GAAG,GAAG,CAAC;AACf,CAAC;AAED,MAAM,UAAU,qBAAqB;IACnC,OAAO,MAAM,KAAK,IAAI,CAAC;AACzB,CAAC;AAED,SAAS,aAAa;IACpB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,UAAU,IAAI,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,OAAO,CAAC,UAAU,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,CAAC,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC,CAAC;YAC3E,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,YAAY,CAAC,gBAAgB,CAAC;YACzC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,CAAC,GAAsB,EAAE,EAAE;YACtC,IAAI,GAAG,EAAE,CAAC;gBACR,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACnE,CAAC;iBAAM,CAAC;gBACN,UAAU,GAAG,IAAI,CAAC;gBAClB,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAW,EACX,QAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,MAAM,aAAa,EAAE,CAAC;IACnC,OAAO,IAAI,OAAO,CAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,IAAI,CAAC,OAAO,CAAC;YACX,OAAO,EAAE,GAAG;YACZ,KAAK;YACL,QAAQ,EAAE,CAAC,GAAsB,EAAE,KAAc,EAAE,IAA2B,EAAE,EAAE;gBAChF,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,CAAC,IAAI,KAAK,CAAC,2BAA2B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBAC9D,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,CAAC,IAAI,IAAI,EAAE,CAAQ,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;SACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,IAAI,CAAC,UAAU;QAAE,OAAO;IACxB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,UAAW,CAAC,OAAO,CAAC,CAAC,GAAsB,EAAE,EAAE;YAC7C,UAAU,GAAG,IAAI,CAAC;YAClB,IAAI,GAAG;gBAAE,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;;gBACrE,OAAO,EAAE,CAAC;QACjB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/dateHelper.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Auto-fill missing SFR date pair.
+ *
+ * Without dates the SFR API returns all-time data, which is often too
+ * broad (e.g. top buyers across 10+ years).  Default to last 1 year so
+ * results reflect recent activity.
+ *
+ * - Neither provided   → default to last 1 year
+ * - Min without max     → default max to today
+ * - Max without min     → default min to 1 year before max
+ * - Invalid date values → treated as unset (fall through to defaults)
+ */
+export declare function autoFillDateRange(params: Record<string, unknown>, minKey?: string, maxKey?: string): void;
+/**
+ * Auto-fill PLR start_date/end_date when NEITHER is provided.
+ *
+ * The PLR backend defaults to a 10-year window (MAX_DATE_RANGE_DAYS=3650)
+ * when no dates are given.  Since pl_base data only goes back to 2021,
+ * the "previous" comparison period (2006-2016) has zero rows, causing
+ * period-over-period endpoints (msa_rankings, borrower_rankings, etc.)
+ * to return 0 results.
+ *
+ * Default: last 1 year → recent period has data AND previous period
+ * (the year before) also has data.
+ */
+export declare function autoFillPlrDates(params: Record<string, unknown>, startKey?: string, endKey?: string): void;

package/dist/tools/dateHelper.js

@@ -0,0 +1,86 @@
+/** Check if a string is a valid YYYY-MM-DD date. */
+function isValidDateStr(v) {
+    if (typeof v !== "string")
+        return false;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(v))
+        return false;
+    const d = new Date(v + "T00:00:00Z");
+    return !isNaN(d.getTime());
+}
+/**
+ * Auto-fill missing SFR date pair.
+ *
+ * Without dates the SFR API returns all-time data, which is often too
+ * broad (e.g. top buyers across 10+ years).  Default to last 1 year so
+ * results reflect recent activity.
+ *
+ * - Neither provided   → default to last 1 year
+ * - Min without max     → default max to today
+ * - Max without min     → default min to 1 year before max
+ * - Invalid date values → treated as unset (fall through to defaults)
+ */
+export function autoFillDateRange(params, minKey = "sales_date_min", maxKey = "sales_date_max") {
+    // Treat invalid dates as unset
+    if (params[minKey] !== undefined && !isValidDateStr(params[minKey])) {
+        delete params[minKey];
+    }
+    if (params[maxKey] !== undefined && !isValidDateStr(params[maxKey])) {
+        delete params[maxKey];
+    }
+    const hasMin = params[minKey] !== undefined;
+    const hasMax = params[maxKey] !== undefined;
+    if (!hasMin && !hasMax) {
+        const now = new Date();
+        params[maxKey] = now.toISOString().slice(0, 10);
+        const oneYearAgo = new Date(now);
+        oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1);
+        params[minKey] = oneYearAgo.toISOString().slice(0, 10);
+    }
+    else if (hasMin && !hasMax) {
+        params[maxKey] = new Date().toISOString().slice(0, 10);
+    }
+    else if (hasMax && !hasMin) {
+        const max = new Date(params[maxKey]);
+        max.setFullYear(max.getFullYear() - 1);
+        params[minKey] = max.toISOString().slice(0, 10);
+    }
+}
+/**
+ * Auto-fill PLR start_date/end_date when NEITHER is provided.
+ *
+ * The PLR backend defaults to a 10-year window (MAX_DATE_RANGE_DAYS=3650)
+ * when no dates are given.  Since pl_base data only goes back to 2021,
+ * the "previous" comparison period (2006-2016) has zero rows, causing
+ * period-over-period endpoints (msa_rankings, borrower_rankings, etc.)
+ * to return 0 results.
+ *
+ * Default: last 1 year → recent period has data AND previous period
+ * (the year before) also has data.
+ */
+export function autoFillPlrDates(params, startKey = "start_date", endKey = "end_date") {
+    // Treat invalid dates as unset
+    if (params[startKey] !== undefined && !isValidDateStr(params[startKey])) {
+        delete params[startKey];
+    }
+    if (params[endKey] !== undefined && !isValidDateStr(params[endKey])) {
+        delete params[endKey];
+    }
+    const hasStart = params[startKey] !== undefined;
+    const hasEnd = params[endKey] !== undefined;
+    if (!hasStart && !hasEnd) {
+        const now = new Date();
+        params[endKey] = now.toISOString().slice(0, 10);
+        const oneYearAgo = new Date(now);
+        oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1);
+        params[startKey] = oneYearAgo.toISOString().slice(0, 10);
+    }
+    else if (hasStart && !hasEnd) {
+        params[endKey] = new Date().toISOString().slice(0, 10);
+    }
+    else if (hasEnd && !hasStart) {
+        const end = new Date(params[endKey]);
+        end.setFullYear(end.getFullYear() - 1);
+        params[startKey] = end.toISOString().slice(0, 10);
+    }
+}
+//# sourceMappingURL=dateHelper.js.map

package/dist/tools/dateHelper.js.map

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

package/dist/tools/formatters.d.ts

@@ -0,0 +1,66 @@
+import type { NextAction } from "./nextActions.js";
+/** Truncate JSON to a max length for inclusion in tool responses */
+export declare function truncatedJson(data: unknown, maxLen?: number): string;
+/** Format a key-value summary as markdown */
+export declare function kvSummary(pairs: [string, unknown][]): string;
+/** Format an array of records as a compact markdown table */
+export declare function markdownTable(headers: string[], rows: (string | number | null | undefined)[][]): string;
+/** Build a standard MCP text response */
+export declare function textContent(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Build a response with both human-readable text and machine-readable structured data */
+export declare function structuredResult(text: string, data: Record<string, unknown>, nextActions?: NextAction[]): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+};
+/** Build an error response for tool handlers */
+export declare function errorContent(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * Format an API error into a standard error response.
+ * Replaces the duplicated catch block pattern across all tool files.
+ */
+export declare function handleToolError(err: unknown, toolName: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/** Format a dollar amount with adaptive B/M/K suffix */
+export declare function fmtDollars(v: unknown): string;
+/** Format a number as a percentage with 1 decimal, e.g. 11.94 → "11.9%" */
+export declare function fmtPercent(v: unknown): string;
+/** Format an ISO timestamp into a readable period label */
+export declare function fmtPeriod(key: string, v: string): string;
+/** Copy all defined values from args into a flat query object. */
+export declare function argsToQuery(args: Record<string, unknown>): Record<string, unknown>;
+export type FieldSpec = {
+    /** API field name */
+    key: string;
+    /** Display label */
+    label: string;
+    /** Optional formatter */
+    fmt?: (v: unknown) => string;
+};
+/**
+ * Map API response fields to display pairs, tracking unmapped keys.
+ * Returns { pairs, unmapped } for downstream drift detection.
+ * Adoption across tools is deferred to a separate PR.
+ */
+export declare function mapWithCoverage(data: Record<string, unknown>, specs: FieldSpec[], ignoreKeys?: string[]): {
+    pairs: [string, unknown][];
+    unmapped: string[];
+};

package/dist/tools/formatters.js

@@ -0,0 +1,219 @@
+import { ApiError } from "../services/httpClient.js";
+/** Truncate JSON to a max length for inclusion in tool responses */
+export function truncatedJson(data, maxLen = 5000) {
+    const raw = JSON.stringify(data, null, 2) ?? "null";
+    if (raw.length <= maxLen)
+        return raw;
+    return raw.slice(0, maxLen) + "\n... (truncated)";
+}
+/** Format a key-value summary as markdown */
+export function kvSummary(pairs) {
+    return pairs
+        .filter(([, v]) => v != null && v !== "")
+        .map(([k, v]) => `**${k}:** ${v}`)
+        .join("\n");
+}
+/** Escape a cell value for safe inclusion in a markdown table */
+function escapeCell(v) {
+    if (v == null)
+        return "—";
+    return String(v).replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+/** Format an array of records as a compact markdown table */
+export function markdownTable(headers, rows) {
+    if (rows.length === 0)
+        return "_No results_";
+    const headerRow = `| ${headers.map(escapeCell).join(" | ")} |`;
+    const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+    const dataRows = rows.map((row) => `| ${row.map(escapeCell).join(" | ")} |`);
+    return [headerRow, separator, ...dataRows].join("\n");
+}
+/** Build a standard MCP text response */
+export function textContent(text) {
+    return { content: [{ type: "text", text }] };
+}
+// ---------------------------------------------------------------------------
+// Structured output size management
+// ---------------------------------------------------------------------------
+/**
+ * Max characters for structuredContent JSON (roughly ~12K tokens).
+ * Claude Code warns at 10K tokens and hard-limits at 25K tokens for MCP
+ * tool results. Since both content + structuredContent may reach the model,
+ * we budget ~12K tokens for structured and ~6K for markdown.
+ */
+const MAX_STRUCTURED_CHARS = 50_000;
+/** Max items in any array within structuredContent */
+const MAX_ARRAY_ITEMS = 50;
+/** Max nesting depth before truncation */
+const MAX_DEPTH = 8;
+/** Max string length for any single field */
+const MAX_STRING_CHARS = 2000;
+/**
+ * Recursively enforce size limits on a JSON-serializable value.
+ * Caps arrays, string lengths, and nesting depth.
+ * Mutates the report object to track what was truncated.
+ */
+function truncateValue(value, depth, report) {
+    if (depth > MAX_DEPTH) {
+        report.truncated = true;
+        if (!report.reasons.includes("maxDepth"))
+            report.reasons.push("maxDepth");
+        return "[truncated: max depth]";
+    }
+    if (typeof value === "string" && value.length > MAX_STRING_CHARS) {
+        report.truncated = true;
+        if (!report.reasons.includes("maxStringLength"))
+            report.reasons.push("maxStringLength");
+        return value.slice(0, MAX_STRING_CHARS) + "...[truncated]";
+    }
+    if (Array.isArray(value)) {
+        const capped = value.length > MAX_ARRAY_ITEMS;
+        if (capped) {
+            report.truncated = true;
+            if (!report.reasons.includes("maxArrayItems"))
+                report.reasons.push("maxArrayItems");
+        }
+        const slice = capped ? value.slice(0, MAX_ARRAY_ITEMS) : value;
+        const mapped = slice.map((v) => truncateValue(v, depth + 1, report));
+        if (capped) {
+            mapped.push({ _truncated: true, _total: value.length, _returned: MAX_ARRAY_ITEMS });
+        }
+        return mapped;
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = truncateValue(v, depth + 1, report);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Enforce size limits on structuredContent data.
+ * Returns the (possibly truncated) data. Adds _outputMeta if truncation occurred.
+ */
+function capStructuredOutput(data) {
+    // Quick check: if small enough, return as-is
+    const raw = JSON.stringify(data);
+    if (raw.length <= MAX_STRUCTURED_CHARS)
+        return data;
+    // Apply recursive truncation
+    const report = { truncated: false, reasons: ["outputSizeLimit"] };
+    const capped = truncateValue(data, 0, report);
+    capped._outputMeta = {
+        truncated: true,
+        originalSizeChars: raw.length,
+        cappedSizeChars: JSON.stringify(capped).length,
+        reasons: report.reasons,
+        hint: "Result was truncated to stay within MCP output limits. Use pagination params or narrow your query for complete data.",
+    };
+    return capped;
+}
+/** Build a response with both human-readable text and machine-readable structured data */
+export function structuredResult(text, data, nextActions) {
+    const structured = capStructuredOutput(data);
+    if (nextActions?.length)
+        structured.nextActions = nextActions;
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: structured,
+    };
+}
+/** Build an error response for tool handlers */
+export function errorContent(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+/** Strip stack traces and internal file paths from error details. */
+function sanitizeErrorDetail(raw, maxLen = 500) {
+    return raw
+        .replace(/\s+at\s+.+\(.+\)/g, "") // JS stack trace lines
+        .replace(/\/[^\s:]+\.[jt]s:\d+/g, "") // JS file paths
+        .replace(/File\s+"[^"]+",\s+line\s+\d+[^\n]*/g, "") // Python traceback lines
+        .replace(/\/[^\s:]+\.py:\d+/g, "") // Python file paths
+        .replace(/Traceback \(most recent call last\):[\s\S]*/g, "") // Full Python traceback block
+        .slice(0, maxLen);
+}
+/**
+ * Format an API error into a standard error response.
+ * Replaces the duplicated catch block pattern across all tool files.
+ */
+export function handleToolError(err, toolName) {
+    let detail;
+    if (err instanceof ApiError) {
+        const raw = JSON.stringify(err.details);
+        detail = `HTTP ${err.status} - ${sanitizeErrorDetail(raw)}`;
+    }
+    else if (err instanceof Error) {
+        detail = sanitizeErrorDetail(err.message);
+    }
+    else {
+        detail = sanitizeErrorDetail(String(err));
+    }
+    return errorContent(`${toolName} failed: ${detail}`);
+}
+/** Format a dollar amount with adaptive B/M/K suffix */
+export function fmtDollars(v) {
+    if (v == null)
+        return "—";
+    const n = Number(v);
+    if (isNaN(n))
+        return "—";
+    if (Math.abs(n) >= 1e9)
+        return `$${(n / 1e9).toFixed(2)}B`;
+    if (Math.abs(n) >= 1e6)
+        return `$${(n / 1e6).toFixed(1)}M`;
+    if (Math.abs(n) >= 1e3)
+        return `$${(n / 1e3).toFixed(0)}K`;
+    return `$${n.toLocaleString()}`;
+}
+/** Format a number as a percentage with 1 decimal, e.g. 11.94 → "11.9%" */
+export function fmtPercent(v) {
+    if (v == null)
+        return "—";
+    const n = Number(v);
+    if (isNaN(n))
+        return "—";
+    return `${n.toFixed(1)}%`;
+}
+/** Format an ISO timestamp into a readable period label */
+export function fmtPeriod(key, v) {
+    const d = new Date(v);
+    if (isNaN(d.getTime()))
+        return v;
+    const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+    if (/quarter/i.test(key)) {
+        const q = Math.ceil((d.getMonth() + 1) / 3);
+        return `Q${q} ${d.getFullYear()}`;
+    }
+    return `${months[d.getMonth()]} ${d.getFullYear()}`;
+}
+/** Copy all defined values from args into a flat query object. */
+export function argsToQuery(args) {
+    const query = {};
+    for (const [key, val] of Object.entries(args)) {
+        if (val !== undefined)
+            query[key] = val;
+    }
+    return query;
+}
+/**
+ * Map API response fields to display pairs, tracking unmapped keys.
+ * Returns { pairs, unmapped } for downstream drift detection.
+ * Adoption across tools is deferred to a separate PR.
+ */
+export function mapWithCoverage(data, specs, ignoreKeys = []) {
+    const mapped = new Set();
+    const pairs = [];
+    for (const spec of specs) {
+        const val = data[spec.key];
+        mapped.add(spec.key);
+        if (val == null || val === "")
+            continue;
+        pairs.push([spec.label, spec.fmt ? spec.fmt(val) : val]);
+    }
+    const ignoreSet = new Set(ignoreKeys);
+    const unmapped = Object.keys(data).filter((k) => !mapped.has(k) && !ignoreSet.has(k) && data[k] != null);
+    return { pairs, unmapped };
+}
+//# sourceMappingURL=formatters.js.map

package/dist/tools/formatters.js.map

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

package/dist/tools/health.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SfrClient } from "../services/sfr.js";
+import type { PlrClient } from "../services/plr.js";
+import type { AppConfig } from "../config.js";
+export declare function registerHealthTool(server: McpServer, sfr: SfrClient | null, plr: PlrClient | null, config: AppConfig): void;

package/dist/tools/health.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { structuredResult } from "./formatters.js";
+import { registerToolSafe } from "./registerToolSafe.js";
+export function registerHealthTool(server, sfr, plr, config) {
+    registerToolSafe(server, "sfra_health", {
+        title: "SFRA MCP health check",
+        description: "Check connectivity to all configured APIs. " +
+            "Returns status and latency for each service. " +
+            "Use this to verify your API tokens are working.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const lines = ["## SFRA MCP Health Check", ""];
+        const structured = {};
+        // Run health checks in parallel when both are configured
+        const [sfrHealth, plrHealth] = await Promise.all([
+            sfr && config.sfr ? sfr.healthCheck() : null,
+            plr && config.plr ? plr.healthCheck() : null,
+        ]);
+        if (sfrHealth) {
+            lines.push(`**SFR API**`, `  Status: ${sfrHealth.ok ? "OK" : "FAILED"}`, `  Latency: ${sfrHealth.latencyMs}ms`, "");
+            structured.sfr = { ok: sfrHealth.ok, latencyMs: sfrHealth.latencyMs };
+        }
+        else {
+            lines.push("**SFR API** — not configured", "  Add SFR_API_TOKEN to enable 21 property, buyer, and market tools", "");
+            structured.sfr = { configured: false };
+        }
+        if (plrHealth) {
+            lines.push(`**PLR API**`, `  Status: ${plrHealth.ok ? "OK" : "FAILED"}`, `  Latency: ${plrHealth.latencyMs}ms`);
+            structured.plr = { ok: plrHealth.ok, latencyMs: plrHealth.latencyMs };
+        }
+        else {
+            lines.push("**PLR API** — not configured", "  Add PLR_API_TOKEN to enable 15 lending and borrower tools");
+            structured.plr = { configured: false };
+        }
+        return structuredResult(lines.join("\n"), structured);
+    });
+}
+//# sourceMappingURL=health.js.map

package/dist/tools/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,GAAqB,EACrB,GAAqB,EACrB,MAAiB;IAEjB,gBAAgB,CAAC,MAAM,EACrB,aAAa,EACb;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,6CAA6C;YAC7C,+CAA+C;YAC/C,iDAAiD;QACnD,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;KAC1B,EACD,KAAK,IAAI,EAAE;QACT,MAAM,KAAK,GAAa,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;QACzD,MAAM,UAAU,GAA4B,EAAE,CAAC;QAE/C,yDAAyD;QACzD,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC/C,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;YAC5C,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;SAC7C,CAAC,CAAC;QAEH,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CACR,aAAa,EACb,aAAa,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,EAC7C,cAAc,SAAS,CAAC,SAAS,IAAI,EACrC,EAAE,CACH,CAAC;YACF,UAAU,CAAC,GAAG,GAAG,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;QACxE,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CACR,8BAA8B,EAC9B,oEAAoE,EACpE,EAAE,CACH,CAAC;YACF,UAAU,CAAC,GAAG,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;QACzC,CAAC;QAED,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CACR,aAAa,EACb,aAAa,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,EAC7C,cAAc,SAAS,CAAC,SAAS,IAAI,CACtC,CAAC;YACF,UAAU,CAAC,GAAG,GAAG,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;QACxE,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CACR,8BAA8B,EAC9B,6DAA6D,CAC9D,CAAC;YACF,UAAU,CAAC,GAAG,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;QACzC,CAAC;QAED,OAAO,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;IACxD,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/nextActions.d.ts

@@ -0,0 +1,10 @@
+/** Structured next-action hint attached to tool output */
+export interface NextAction {
+    tool: string;
+    why: string;
+    args?: Record<string, unknown>;
+}
+/** Create a NextAction, omitting args when empty */
+export declare function action(tool: string, why: string, args?: Record<string, unknown>): NextAction;
+/** Extract common SFR location args for passing to other tools */
+export declare function locationArgs(args: Record<string, unknown>): Record<string, string>;

package/dist/tools/nextActions.js

@@ -0,0 +1,23 @@
+/** Create a NextAction, omitting args when empty */
+export function action(tool, why, args) {
+    const a = { tool, why };
+    if (args && Object.keys(args).length > 0)
+        a.args = args;
+    return a;
+}
+/** Extract common SFR location args for passing to other tools */
+export function locationArgs(args) {
+    const loc = {};
+    if (args.search_type)
+        loc.search_type = String(args.search_type);
+    if (args.state)
+        loc.state = String(args.state);
+    if (args.city)
+        loc.city = String(args.city);
+    if (args.zips)
+        loc.zips = String(args.zips);
+    if (args.msa)
+        loc.msa = String(args.msa);
+    return loc;
+}
+//# sourceMappingURL=nextActions.js.map

package/dist/tools/nextActions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextActions.js","sourceRoot":"","sources":["../../src/tools/nextActions.ts"],"names":[],"mappings":"AAOA,oDAAoD;AACpD,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,GAAW,EAAE,IAA8B;IAC9E,MAAM,CAAC,GAAe,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IACpC,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,YAAY,CAAC,IAA6B;IACxD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,IAAI,IAAI,CAAC,WAAW;QAAE,GAAG,CAAC,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,IAAI,CAAC,IAAI;QAAE,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,IAAI;QAAE,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,GAAG;QAAE,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/tools/plr/borrowerContacts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PlrClient } from "../../services/plr.js";
+export declare function registerBorrowerContactsTool(server: McpServer, plr: PlrClient): void;