@cyanheads/fema-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/fema-search-nfip.tool.js

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview Tool: fema_search_nfip — NFIP flood insurance claims with DataCanvas spillover.
+ * @module mcp-server/tools/definitions/fema-search-nfip
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { spillover } from '@cyanheads/mcp-ts-core/canvas';
+import { getCanvas } from '../../../services/canvas/canvas-accessor.js';
+import { escapeODataString, getOpenFemaService } from '../../../services/openfema/openfema-service.js';
+/** Inline preview budget — ~25k tokens of JSON. */
+const PREVIEW_CHARS = 100_000;
+/** Cap on rows registered to canvas. */
+const MAX_CANVAS_ROWS = 50_000;
+/**
+ * Explicit DuckDB schema for NFIP canvas tables. All fields are nullable to
+ * prevent NOT NULL constraint failures during append: the sniff-based schema
+ * inference marks a column NOT NULL when every row in the sniff window has a
+ * non-null value — but NFIP data is sparse and later rows may omit fields
+ * that happened to be present in the first N rows.
+ */
+const NFIP_CANVAS_SCHEMA = [
+    { name: 'state', type: 'VARCHAR', nullable: true },
+    { name: 'county_code', type: 'VARCHAR', nullable: true },
+    { name: 'zip_code', type: 'VARCHAR', nullable: true },
+    { name: 'date_of_loss', type: 'VARCHAR', nullable: true },
+    { name: 'year_of_loss', type: 'INTEGER', nullable: true },
+    { name: 'amount_paid_building', type: 'DOUBLE', nullable: true },
+    { name: 'amount_paid_contents', type: 'DOUBLE', nullable: true },
+    { name: 'building_damage_amount', type: 'DOUBLE', nullable: true },
+    { name: 'contents_damage_amount', type: 'DOUBLE', nullable: true },
+    { name: 'rated_flood_zone', type: 'VARCHAR', nullable: true },
+    { name: 'cause_of_damage', type: 'VARCHAR', nullable: true },
+    { name: 'occupancy_type', type: 'INTEGER', nullable: true },
+];
+export const femaSearchNfip = tool('fema_search_nfip', {
+    title: 'Search NFIP Flood Insurance Claims',
+    description: 'Search National Flood Insurance Program (NFIP) claims data by state, county, ZIP code, and year range. ' +
+        'Returns claim counts, amounts paid on building and contents, flood zones, and loss years. ' +
+        'state is required — the full NFIP dataset is 2.7 million rows; unfiltered access is prohibited. ' +
+        'When DataCanvas is enabled (CANVAS_PROVIDER_TYPE=duckdb) and results exceed the inline preview, ' +
+        'the full result set is staged on a canvas for SQL aggregation via fema_dataframe_query. ' +
+        'Use fema_dataframe_describe to inspect the staged table schema before writing SQL. ' +
+        'Without canvas, results are returned inline up to the limit.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        state: z
+            .string()
+            .length(2)
+            .toUpperCase()
+            .describe('Two-letter US state code (required). NFIP dataset is 2.7M rows — state filter is mandatory.'),
+        county_code: z
+            .string()
+            .optional()
+            .describe('County code to narrow results within the state (e.g., 201 for Harris County TX). Use with state.'),
+        zip_code: z.string().optional().describe('ZIP code to narrow results to a specific area.'),
+        year_from: z
+            .number()
+            .int()
+            .min(1970)
+            .max(2100)
+            .optional()
+            .describe('Start year of loss, inclusive (e.g., 2020).'),
+        year_to: z
+            .number()
+            .int()
+            .min(1970)
+            .max(2100)
+            .optional()
+            .describe('End year of loss, inclusive (e.g., 2023).'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(10000)
+            .default(1000)
+            .describe('Maximum rows to fetch (1–10000, default 1000).'),
+        canvas_id: z
+            .string()
+            .optional()
+            .describe('Optional canvas ID from a prior call. Omit to create a fresh canvas. The response returns the canvas_id to pass to fema_dataframe_query.'),
+    }),
+    output: z.object({
+        claims: z
+            .array(z
+            .object({
+            state: z
+                .string()
+                .optional()
+                .describe('Two-letter state code. Absent when not in the record.'),
+            county_code: z
+                .string()
+                .optional()
+                .describe('County code (e.g., 201 for Harris County TX). Absent when not recorded.'),
+            zip_code: z
+                .string()
+                .optional()
+                .describe('5-digit ZIP code of the insured property. Absent when not recorded.'),
+            date_of_loss: z
+                .string()
+                .optional()
+                .describe('ISO 8601 date the flood loss occurred. Absent when not recorded.'),
+            year_of_loss: z
+                .number()
+                .optional()
+                .describe('Calendar year the flood loss occurred. Absent when not recorded.'),
+            amount_paid_building: z
+                .number()
+                .optional()
+                .describe('NFIP claim payment for the building structure in USD. Absent when zero or not recorded.'),
+            amount_paid_contents: z
+                .number()
+                .optional()
+                .describe('NFIP claim payment for contents (personal property) in USD. Absent when zero or not recorded.'),
+            building_damage_amount: z
+                .number()
+                .optional()
+                .describe('Estimated total building damage in USD (may exceed paid amount). Absent when not assessed.'),
+            contents_damage_amount: z
+                .number()
+                .optional()
+                .describe('Estimated total contents damage in USD (may exceed paid amount). Absent when not assessed.'),
+            rated_flood_zone: z
+                .string()
+                .optional()
+                .describe('FEMA flood zone designation at the property (e.g., AE, X, VE). Absent when not recorded.'),
+            cause_of_damage: z
+                .string()
+                .optional()
+                .describe('Primary cause of the flood damage (e.g., "Flooding", "Tidal Overflow"). Absent when not recorded.'),
+            occupancy_type: z
+                .number()
+                .optional()
+                .describe('NFIP occupancy type code (e.g., 1=Single Family, 2=2-4 Family, 6=Non-Residential). Absent when not recorded.'),
+        })
+            .describe('A single NFIP flood insurance claim record.'))
+            .describe('Inline preview of claim records (first N rows). Full dataset available via canvas_id when spilled=true.'),
+        total_count: z
+            .number()
+            .describe('Total matching claims in the filtered dataset before the limit.'),
+        returned_count: z.number().describe('Number of claim records in the inline preview.'),
+        canvas_id: z
+            .string()
+            .optional()
+            .describe('Canvas ID for the staged full result set. Pass to fema_dataframe_query and fema_dataframe_describe. Present when canvas is enabled.'),
+        canvas_table: z
+            .string()
+            .optional()
+            .describe('DuckDB table name on the canvas holding all fetched rows. Reference in SQL FROM clauses. Present when spilled=true.'),
+        spilled: z
+            .boolean()
+            .describe('True when the full result set was staged on DataCanvas; use canvas_id + fema_dataframe_query for SQL analysis. False when all results fit inline.'),
+        truncated: z
+            .boolean()
+            .optional()
+            .describe('True when the canvas row cap (50,000) was reached before all matching rows were staged. Apply tighter filters (county_code, zip_code, year range) for a complete set.'),
+    }),
+    enrichment: {
+        notice: z.string().optional().describe('Guidance on canvas usage or result scope.'),
+    },
+    async handler(input, ctx) {
+        const filterParts = [`state eq '${escapeODataString(input.state)}'`];
+        if (input.county_code?.trim()) {
+            filterParts.push(`countyCode eq '${escapeODataString(input.county_code)}'`);
+        }
+        if (input.zip_code?.trim()) {
+            filterParts.push(`reportedZipCode eq '${escapeODataString(input.zip_code)}'`);
+        }
+        if (input.year_from != null) {
+            filterParts.push(`yearOfLoss ge ${input.year_from}`);
+        }
+        if (input.year_to != null) {
+            filterParts.push(`yearOfLoss le ${input.year_to}`);
+        }
+        const svc = getOpenFemaService();
+        const { rows: rawRows, count } = await svc.fetchNfipClaims({
+            filter: filterParts.join(' and '),
+            orderby: 'dateOfLoss desc',
+            top: input.limit,
+        }, ctx);
+        const rows = rawRows.map((r) => ({
+            state: r.state ?? null,
+            county_code: r.countyCode ?? null,
+            zip_code: r.reportedZipCode ?? null,
+            date_of_loss: r.dateOfLoss ?? null,
+            year_of_loss: r.yearOfLoss ?? null,
+            amount_paid_building: r.amountPaidOnBuildingClaim ?? null,
+            amount_paid_contents: r.amountPaidOnContentsClaim ?? null,
+            building_damage_amount: r.buildingDamageAmount ?? null,
+            contents_damage_amount: r.contentsDamageAmount ?? null,
+            rated_flood_zone: r.ratedFloodZone ?? null,
+            cause_of_damage: r.causeOfDamage ?? null,
+            occupancy_type: r.occupancyType ?? null,
+        }));
+        /** Convert canvas rows (null fields) to the output schema shape (absent fields). */
+        function toOutputRows(canvasRows) {
+            return canvasRows.map((r) => ({
+                ...(r.state != null ? { state: r.state } : {}),
+                ...(r.county_code != null ? { county_code: r.county_code } : {}),
+                ...(r.zip_code != null ? { zip_code: r.zip_code } : {}),
+                ...(r.date_of_loss != null ? { date_of_loss: r.date_of_loss } : {}),
+                ...(r.year_of_loss != null ? { year_of_loss: r.year_of_loss } : {}),
+                ...(r.amount_paid_building != null ? { amount_paid_building: r.amount_paid_building } : {}),
+                ...(r.amount_paid_contents != null ? { amount_paid_contents: r.amount_paid_contents } : {}),
+                ...(r.building_damage_amount != null
+                    ? { building_damage_amount: r.building_damage_amount }
+                    : {}),
+                ...(r.contents_damage_amount != null
+                    ? { contents_damage_amount: r.contents_damage_amount }
+                    : {}),
+                ...(r.rated_flood_zone != null ? { rated_flood_zone: r.rated_flood_zone } : {}),
+                ...(r.cause_of_damage != null ? { cause_of_damage: r.cause_of_damage } : {}),
+                ...(r.occupancy_type != null ? { occupancy_type: r.occupancy_type } : {}),
+            }));
+        }
+        // Try canvas spillover if available
+        const canvas = getCanvas();
+        if (canvas) {
+            const instance = await canvas.acquire(input.canvas_id, ctx);
+            const result = await spillover({
+                canvas: instance,
+                source: rows,
+                schema: NFIP_CANVAS_SCHEMA,
+                previewChars: PREVIEW_CHARS,
+                caps: { maxRows: MAX_CANVAS_ROWS },
+                signal: ctx.signal,
+            });
+            if (result.spilled) {
+                ctx.enrich.notice(`Results staged on canvas table "${result.handle.tableName}". Use fema_dataframe_query with canvas_id "${instance.canvasId}" to run SQL aggregations.`);
+                ctx.log.info('NFIP claims spilled to canvas', {
+                    canvasId: instance.canvasId,
+                    tableName: result.handle.tableName,
+                    rowCount: result.handle.rowCount,
+                });
+                return {
+                    claims: toOutputRows(result.previewRows),
+                    total_count: count,
+                    returned_count: result.previewRows.length,
+                    canvas_id: instance.canvasId,
+                    canvas_table: result.handle.tableName,
+                    spilled: true,
+                    ...(result.truncated ? { truncated: true } : {}),
+                };
+            }
+            // Fits in preview — still surface canvas_id for potential follow-up queries
+            ctx.log.info('NFIP claims fit inline', { rowCount: result.previewRows.length, count });
+            return {
+                claims: toOutputRows(result.previewRows),
+                total_count: count,
+                returned_count: result.previewRows.length,
+                canvas_id: instance.canvasId,
+                canvas_table: '',
+                spilled: false,
+            };
+        }
+        // Canvas disabled — inline only
+        ctx.log.info('NFIP claims inline (canvas disabled)', { returned: rows.length, count });
+        if (count > rows.length) {
+            ctx.enrich.notice(`Showing ${rows.length} of ${count} matching claims. Enable CANVAS_PROVIDER_TYPE=duckdb for full analytical access, or increase limit and use offset for pagination.`);
+        }
+        return {
+            claims: toOutputRows(rows),
+            total_count: count,
+            returned_count: rows.length,
+            spilled: false,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`**${result.returned_count} of ${result.total_count} NFIP claims** | Spilled: ${result.spilled}`);
+        if (result.spilled && result.canvas_id) {
+            lines.push(`**Canvas ID:** ${result.canvas_id} | **Table:** ${result.canvas_table ?? 'unknown'}`);
+            lines.push(`Use fema_dataframe_query with this canvas_id for SQL aggregations.\n`);
+        }
+        if (result.truncated) {
+            lines.push(`_Note: canvas row cap hit — result set truncated._\n`);
+        }
+        for (const c of result.claims) {
+            const parts = [];
+            if (c.state)
+                parts.push(`State: ${c.state}`);
+            if (c.county_code)
+                parts.push(`County: ${c.county_code}`);
+            if (c.zip_code)
+                parts.push(`ZIP: ${c.zip_code}`);
+            if (c.date_of_loss)
+                parts.push(`Loss: ${c.date_of_loss}`);
+            if (c.year_of_loss != null)
+                parts.push(`Year: ${c.year_of_loss}`);
+            if (c.rated_flood_zone)
+                parts.push(`Zone: ${c.rated_flood_zone}`);
+            if (c.cause_of_damage)
+                parts.push(`Cause: ${c.cause_of_damage}`);
+            if (c.occupancy_type)
+                parts.push(`Occupancy: ${c.occupancy_type}`);
+            if (c.amount_paid_building != null)
+                parts.push(`Bldg Paid: $${c.amount_paid_building.toLocaleString()}`);
+            if (c.amount_paid_contents != null)
+                parts.push(`Contents Paid: $${c.amount_paid_contents.toLocaleString()}`);
+            if (c.building_damage_amount != null)
+                parts.push(`Bldg Damage: $${c.building_damage_amount.toLocaleString()}`);
+            if (c.contents_damage_amount != null)
+                parts.push(`Contents Damage: $${c.contents_damage_amount.toLocaleString()}`);
+            lines.push(parts.join(' | '));
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=fema-search-nfip.tool.js.map

package/dist/mcp-server/tools/definitions/fema-search-nfip.tool.js.map

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

package/dist/services/canvas/canvas-accessor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Canvas accessor module — holds the optional DataCanvas instance
+ * initialized from CoreServices in createApp's setup() callback.
+ * @module services/canvas/canvas-accessor
+ */
+import type { DataCanvas } from '@cyanheads/mcp-ts-core/canvas';
+export declare const setCanvas: (c: DataCanvas | undefined) => void;
+export declare const getCanvas: () => DataCanvas | undefined;
+//# sourceMappingURL=canvas-accessor.d.ts.map

package/dist/services/canvas/canvas-accessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-accessor.d.ts","sourceRoot":"","sources":["../../../src/services/canvas/canvas-accessor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAIhE,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,GAAG,SAAS,KAAG,IAErD,CAAC;AAEF,eAAO,MAAM,SAAS,QAAO,UAAU,GAAG,SAAoB,CAAC"}

package/dist/services/canvas/canvas-accessor.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Canvas accessor module — holds the optional DataCanvas instance
+ * initialized from CoreServices in createApp's setup() callback.
+ * @module services/canvas/canvas-accessor
+ */
+let _canvas;
+export const setCanvas = (c) => {
+    _canvas = c;
+};
+export const getCanvas = () => _canvas;
+//# sourceMappingURL=canvas-accessor.js.map

package/dist/services/canvas/canvas-accessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-accessor.js","sourceRoot":"","sources":["../../../src/services/canvas/canvas-accessor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,IAAI,OAA+B,CAAC;AAEpC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAyB,EAAQ,EAAE;IAC3D,OAAO,GAAG,CAAC,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,GAA2B,EAAE,CAAC,OAAO,CAAC"}

package/dist/services/openfema/openfema-service.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview OpenFEMA API service — wraps the public OpenFEMA v2 REST API
+ * with OData parameter encoding, response parsing, error classification, and retry logic.
+ * @module services/openfema/openfema-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { OpenFemaQueryOptions, RawDisasterDeclaration, RawHousingAssistance, RawNfipClaim, RawPaProject } from './types.js';
+/**
+ * Escape a string value for embedding in an OData string literal (single-quoted).
+ * OData 3 escapes a literal single quote as two consecutive single quotes ('').
+ * Without this, user-supplied strings containing ' can break out of the literal
+ * and alter the filter structure.
+ */
+export declare function escapeODataString(value: string): string;
+export declare class OpenFemaService {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(_config: AppConfig, _storage: StorageService);
+    /**
+     * Fetch a page from any OpenFEMA dataset.
+     * Returns the data array and total count from the response envelope.
+     */
+    fetchDataset<T>(dataset: string, opts: OpenFemaQueryOptions, ctx: Context): Promise<{
+        rows: T[];
+        count: number;
+    }>;
+    /** Fetch disaster declaration summaries. */
+    fetchDisasters(opts: OpenFemaQueryOptions, ctx: Context): Promise<{
+        rows: RawDisasterDeclaration[];
+        count: number;
+    }>;
+    /** Fetch public assistance funded project details. */
+    fetchPaProjects(opts: OpenFemaQueryOptions, ctx: Context): Promise<{
+        rows: RawPaProject[];
+        count: number;
+    }>;
+    /** Fetch housing assistance — owners or renters. */
+    fetchHousingAssistance(dataset: 'HousingAssistanceOwners' | 'HousingAssistanceRenters', opts: OpenFemaQueryOptions, ctx: Context): Promise<{
+        rows: RawHousingAssistance[];
+        count: number;
+    }>;
+    /** Fetch NFIP claims. */
+    fetchNfipClaims(opts: OpenFemaQueryOptions, ctx: Context): Promise<{
+        rows: RawNfipClaim[];
+        count: number;
+    }>;
+}
+export declare function initOpenFemaService(config: AppConfig, storage: StorageService): void;
+export declare function getOpenFemaService(): OpenFemaService;
+//# sourceMappingURL=openfema-service.d.ts.map

package/dist/services/openfema/openfema-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openfema-service.d.ts","sourceRoot":"","sources":["../../../src/services/openfema/openfema-service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,KAAK,EAGV,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAoBD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAMxD;;;OAGG;IACH,YAAY,CAAC,CAAC,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,oBAAoB,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAqGxC,4CAA4C;IAC5C,cAAc,CACZ,IAAI,EAAE,oBAAoB,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAI7D,sDAAsD;IACtD,eAAe,CACb,IAAI,EAAE,oBAAoB,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAInD,oDAAoD;IACpD,sBAAsB,CACpB,OAAO,EAAE,yBAAyB,GAAG,0BAA0B,EAC/D,IAAI,EAAE,oBAAoB,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3D,yBAAyB;IACzB,eAAe,CACb,IAAI,EAAE,oBAAoB,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAGpD;AAMD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAEpF;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD"}

package/dist/services/openfema/openfema-service.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview OpenFEMA API service — wraps the public OpenFEMA v2 REST API
+ * with OData parameter encoding, response parsing, error classification, and retry logic.
+ * @module services/openfema/openfema-service
+ */
+import { invalidParams, notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+/**
+ * Escape a string value for embedding in an OData string literal (single-quoted).
+ * OData 3 escapes a literal single quote as two consecutive single quotes ('').
+ * Without this, user-supplied strings containing ' can break out of the literal
+ * and alter the filter structure.
+ */
+export function escapeODataString(value) {
+    return value.replace(/'/g, "''");
+}
+/** Build encoded OData query string — uses %24 prefix for $ params (Akamai requirement). */
+function buildODataQuery(opts) {
+    const parts = [];
+    // Always request inline count so we get real totals
+    parts.push('%24inlinecount=allpages');
+    if (opts.filter)
+        parts.push(`%24filter=${encodeURIComponent(opts.filter)}`);
+    if (opts.select)
+        parts.push(`%24select=${encodeURIComponent(opts.select)}`);
+    if (opts.orderby)
+        parts.push(`%24orderby=${encodeURIComponent(opts.orderby)}`);
+    if (opts.top !== undefined)
+        parts.push(`%24top=${opts.top}`);
+    if (opts.skip !== undefined)
+        parts.push(`%24skip=${opts.skip}`);
+    return parts.join('&');
+}
+/** Detect HTML response (Drupal 404 pages). */
+function isHtmlResponse(text) {
+    return /^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text);
+}
+export class OpenFemaService {
+    baseUrl;
+    timeoutMs;
+    constructor(_config, _storage) {
+        const srv = getServerConfig();
+        this.baseUrl = srv.baseUrl;
+        this.timeoutMs = srv.requestTimeoutMs;
+    }
+    /**
+     * Fetch a page from any OpenFEMA dataset.
+     * Returns the data array and total count from the response envelope.
+     */
+    fetchDataset(dataset, opts, ctx) {
+        const qs = buildODataQuery(opts);
+        const url = `${this.baseUrl}/${dataset}?${qs}`;
+        return withRetry(async () => {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+            // Combine the request abort signal with the timeout signal
+            const signal = ctx.signal &&
+                typeof AbortSignal.any ===
+                    'function'
+                ? AbortSignal.any([
+                    ctx.signal,
+                    controller.signal,
+                ])
+                : controller.signal;
+            let response;
+            try {
+                response = await fetch(url, { signal });
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            // HTML content-type = unknown dataset (Drupal 404)
+            const contentType = response.headers.get('content-type') ?? '';
+            if (contentType.includes('text/html') || (!response.ok && contentType.includes('html'))) {
+                throw notFound(`Dataset "${dataset}" not found — API returned HTML instead of JSON. Check the dataset name.`, { reason: 'unknown_dataset', dataset });
+            }
+            const text = await response.text();
+            // Body HTML check as fallback (some error pages send application/json content-type)
+            if (isHtmlResponse(text)) {
+                throw notFound(`Dataset "${dataset}" not found — API returned HTML instead of JSON. Check the dataset name.`, { reason: 'unknown_dataset', dataset });
+            }
+            if (!response.ok) {
+                // Parse structured FEMA error response
+                try {
+                    const errBody = JSON.parse(text);
+                    if (errBody.error?.[0]) {
+                        const e = errBody.error[0];
+                        if (response.status === 400) {
+                            throw invalidParams(`OpenFEMA query error [${e.code}]: ${e.message}`, {
+                                reason: 'invalid_filter',
+                                code: e.code,
+                                name: e.name,
+                            });
+                        }
+                        throw serviceUnavailable(`OpenFEMA API error [${e.code}]: ${e.message}`, {
+                            status: response.status,
+                        });
+                    }
+                }
+                catch (parseErr) {
+                    // Re-throw if it's already a classified McpError
+                    if (parseErr instanceof Error && 'code' in parseErr)
+                        throw parseErr;
+                }
+                throw serviceUnavailable(`OpenFEMA API returned HTTP ${response.status} for dataset "${dataset}".`, { status: response.status, url });
+            }
+            let envelope;
+            try {
+                envelope = JSON.parse(text);
+            }
+            catch {
+                throw serviceUnavailable('OpenFEMA returned non-JSON response — possible upstream error.', { url });
+            }
+            // Data array is keyed by entityName (e.g. "DisasterDeclarationsSummaries")
+            const rows = envelope[dataset] ?? [];
+            // count is in envelope.metadata.count when $inlinecount=allpages is sent
+            const count = typeof envelope.metadata?.count === 'number' ? envelope.metadata.count : rows.length;
+            ctx.log.debug('OpenFEMA fetch complete', { dataset, count, rows: rows.length });
+            return { rows, count };
+        }, {
+            operation: `OpenFemaService.fetchDataset(${dataset})`,
+            // Context is safe to pass — the retry helper strips non-serializable fields before logging.
+            context: ctx,
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /** Fetch disaster declaration summaries. */
+    fetchDisasters(opts, ctx) {
+        return this.fetchDataset('DisasterDeclarationsSummaries', opts, ctx);
+    }
+    /** Fetch public assistance funded project details. */
+    fetchPaProjects(opts, ctx) {
+        return this.fetchDataset('PublicAssistanceFundedProjectsDetails', opts, ctx);
+    }
+    /** Fetch housing assistance — owners or renters. */
+    fetchHousingAssistance(dataset, opts, ctx) {
+        return this.fetchDataset(dataset, opts, ctx);
+    }
+    /** Fetch NFIP claims. */
+    fetchNfipClaims(opts, ctx) {
+        return this.fetchDataset('FimaNfipClaims', opts, ctx);
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initOpenFemaService(config, storage) {
+    _service = new OpenFemaService(config, storage);
+}
+export function getOpenFemaService() {
+    if (!_service) {
+        throw new Error('OpenFemaService not initialized — call initOpenFemaService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=openfema-service.js.map

package/dist/services/openfema/openfema-service.js.map

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