sg-property-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mukul Varshney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# sg-property-mcp
+
+**Singapore property prices, land use, and neighborhood amenities via MCP — no API keys needed.**
+
+An [MCP](https://modelcontextprotocol.io/) server for Singapore property research. Works out of the box with zero configuration.
+
+## What it does
+
+| Tool | Description |
+|------|-------------|
+| **search_area** | Land use and zoning info near a Singapore address |
+| **search_area_by_coords** | Same as above, using coordinates directly |
+| **search_hdb_resale** | Recent HDB resale flat prices by town (2017 onwards) |
+| **search_nearby_amenities** | Schools, MRT, parks, hawker centres, hospitals within a radius |
+| **analyze_results** | AI-powered analysis of your last search |
+| **export_csv** / **export_md** | Save results to CSV or Markdown files |
+
+**8 tools. Zero API keys. Just works.**
+
+## Quick start
+
+### Desktop app
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "sg-property": {
+      "command": "npx",
+      "args": ["-y", "sg-property-mcp"]
+    }
+  }
+}
+```
+
+### CLI (MCP-compatible)
+
+```bash
+# Example for CLI tools that support MCP:
+npx sg-property-mcp
+```
+
+### Manual install
+
+```bash
+npm install -g sg-property-mcp
+```
+
+Then add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "sg-property": {
+      "command": "sg-property-mcp"
+    }
+  }
+}
+```
+
+## Example conversations
+
+> **"What's the land use around Bishan MRT?"**
+> → `search_area` returns zoning types, plot ratios, planning areas
+
+> **"Show me recent 4-room HDB prices in Tampines"**
+> → `search_hdb_resale` returns transactions with prices, block, storey, lease info
+
+> **"What amenities are within 500m of 1.3521, 103.8198?"**
+> → `search_nearby_amenities` finds schools, MRT stations, parks, hawker centres with distances
+
+> **"Analyze the price patterns in those results"**
+> → `analyze_results` provides AI-generated insights on pricing trends
+
+## Data sources
+
+All data comes from free, public APIs. No registration or API keys required.
+
+- Land use zoning — (c) Urban Redevelopment Authority
+- HDB resale prices — Contains information from data.gov.sg accessed under the Singapore Open Data Licence
+- Geocoding & amenities — Data (c) OpenStreetMap contributors
+
+## Requirements
+
+- Node.js 20.6 or later
+- An MCP-compatible client (any MCP desktop app or CLI)
+
+## License
+
+MIT

package/dist/api/arcgis.d.ts

@@ -0,0 +1,2 @@
+import { LandParcel } from "../types.js";
+export declare function queryLandUse(lat: number, lon: number, radiusMeters: number): Promise<LandParcel[]>;

package/dist/api/arcgis.js

@@ -0,0 +1,58 @@
+// URA ArcGIS client — Master Plan 2019 land use spatial query.
+// Finds land parcels within a radius of a point.
+// Free, no API key. Geometry format: longitude,latitude (not lat,lon).
+import { ARCGIS_LAND_USE_URL, ARCGIS_RESULT_LIMIT } from "../config.js";
+export async function queryLandUse(lat, lon, radiusMeters) {
+    // ArcGIS expects longitude,latitude order
+    const body = new URLSearchParams({
+        geometry: `${lon},${lat}`,
+        geometryType: "esriGeometryPoint",
+        inSR: "4326",
+        outSR: "4326",
+        distance: radiusMeters.toString(),
+        units: "esriSRUnit_Meter",
+        spatialRel: "esriSpatialRelIntersects",
+        outFields: "LU_DESC,GPR,REGION_N,PLN_AREA_N,SUBZONE_N",
+        returnGeometry: "false",
+        f: "json",
+        resultRecordCount: ARCGIS_RESULT_LIMIT.toString(),
+    });
+    const response = await fetch(ARCGIS_LAND_USE_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    if (!response.ok) {
+        console.error(`ArcGIS HTTP ${response.status}: ${response.statusText}`);
+        return [];
+    }
+    const data = (await response.json());
+    // ArcGIS can return errors inside a 200 OK
+    if (data.error) {
+        console.error(`ArcGIS error ${data.error.code}: ${data.error.message}`);
+        return [];
+    }
+    if (!data.features) {
+        return [];
+    }
+    // Filter out parcels without a meaningful land use description
+    const parcels = data.features
+        .filter((f) => f.attributes.LU_DESC && f.attributes.LU_DESC.trim() !== "")
+        .map((f) => ({
+        landUse: f.attributes.LU_DESC,
+        grossPlotRatio: f.attributes.GPR ?? null,
+        region: f.attributes.REGION_N ?? "",
+        planningArea: f.attributes.PLN_AREA_N ?? "",
+        subzone: f.attributes.SUBZONE_N ?? "",
+    }));
+    // Deduplicate — multiple polygons often share identical attributes
+    const seen = new Set();
+    return parcels.filter((p) => {
+        const key = `${p.landUse}|${p.grossPlotRatio}|${p.region}|${p.planningArea}|${p.subzone}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+//# sourceMappingURL=arcgis.js.map

package/dist/api/datagov.d.ts

@@ -0,0 +1,6 @@
+import { HdbResaleRecord } from "../types.js";
+export declare function queryHdbResale(town: string, flatType?: string, limit?: number, onWait?: (delayMs: number) => void | Promise<void>): Promise<{
+    records: HdbResaleRecord[];
+    total: number;
+    error?: string;
+}>;

package/dist/api/datagov.js

@@ -0,0 +1,84 @@
+// data.gov.sg client — HDB resale flat prices (2017 onwards).
+// Free, no API key. CKAN datastore API.
+import { DATAGOV_URL, HDB_RESALE_RESOURCE_ID } from "../config.js";
+import { datagovLimiter } from "../rate-limiter.js";
+function isErrorResponse(data) {
+    return "code" in data && "name" in data;
+}
+export async function queryHdbResale(town, flatType, limit = 10, onWait) {
+    const filters = { town: town.toUpperCase() };
+    if (flatType) {
+        filters.flat_type = flatType.toUpperCase();
+    }
+    const params = new URLSearchParams({
+        resource_id: HDB_RESALE_RESOURCE_ID,
+        filters: JSON.stringify(filters),
+        limit: limit.toString(),
+        sort: "month desc",
+    });
+    // Retry with backoff on 429 / rate-limit errors.
+    const MAX_RETRIES = 2;
+    let data;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        await datagovLimiter.wait(onWait);
+        let response;
+        try {
+            response = await fetch(`${DATAGOV_URL}?${params}`);
+        }
+        catch (err) {
+            if (attempt < MAX_RETRIES) {
+                await new Promise((r) => setTimeout(r, (attempt + 1) * 15_000));
+                continue;
+            }
+            console.error(`[datagov] Network error: ${err.message}`);
+            return { records: [], total: 0, error: "Could not reach data service. Retry after 30 seconds delay." };
+        }
+        if (response.status === 429) {
+            const backoffSec = (attempt + 1) * 15; // 15s, 30s, 45s
+            console.error(`[datagov] HTTP 429 — attempt ${attempt + 1}/${MAX_RETRIES + 1}, backing off ${backoffSec}s`);
+            if (attempt < MAX_RETRIES) {
+                await new Promise((r) => setTimeout(r, backoffSec * 1000));
+                continue;
+            }
+            return { records: [], total: 0, error: "Data service is busy. Retry after 30 seconds delay." };
+        }
+        if (!response.ok) {
+            console.error(`[datagov] HTTP ${response.status}: ${response.statusText}`);
+            return { records: [], total: 0, error: "Data service returned an error. Retry after 30 seconds delay." };
+        }
+        data = (await response.json());
+        // Rate limit response: {"code": 24, "name": "TOO_MANY_REQUESTS"}
+        if (isErrorResponse(data)) {
+            console.error(`[datagov] Error response: ${data.name} (code ${data.code})`);
+            if (data.name === "TOO_MANY_REQUESTS" && attempt < MAX_RETRIES) {
+                await new Promise((r) => setTimeout(r, (attempt + 1) * 15_000));
+                continue;
+            }
+            return { records: [], total: 0, error: "Data service is busy. Retry after 30 seconds delay." };
+        }
+        break; // Success — exit retry loop
+    }
+    if (!data || isErrorResponse(data)) {
+        return { records: [], total: 0, error: "Could not reach data service. Retry after 30 seconds delay." };
+    }
+    if (!data.success || !data.result) {
+        return { records: [], total: 0 };
+    }
+    const records = data.result.records.map((r) => ({
+        month: r.month,
+        town: r.town,
+        flatType: r.flat_type,
+        block: r.block,
+        streetName: r.street_name,
+        storeyRange: r.storey_range,
+        floorAreaSqm: r.floor_area_sqm,
+        flatModel: r.flat_model,
+        leaseCommenceDate: r.lease_commence_date,
+        remainingLease: r.remaining_lease,
+        resalePrice: typeof r.resale_price === "number"
+            ? r.resale_price
+            : parseFloat(r.resale_price),
+    }));
+    return { records, total: data.result.total };
+}
+//# sourceMappingURL=datagov.js.map

package/dist/api/nominatim.d.ts

@@ -0,0 +1,2 @@
+import { GeocodingResult } from "../types.js";
+export declare function geocodeAddress(address: string, onWait?: (delayMs: number) => void | Promise<void>): Promise<GeocodingResult | null>;

package/dist/api/nominatim.js

@@ -0,0 +1,32 @@
+// Nominatim (OpenStreetMap) geocoding client.
+// Converts a Singapore address string to lat/lon coordinates.
+// Free, no API key. Rate limit: 1 request per second.
+import { NOMINATIM_URL, USER_AGENT } from "../config.js";
+import { nominatimLimiter } from "../rate-limiter.js";
+export async function geocodeAddress(address, onWait) {
+    const params = new URLSearchParams({
+        q: address,
+        format: "json",
+        limit: "1",
+        countrycodes: "sg",
+    });
+    await nominatimLimiter.wait(onWait);
+    const response = await fetch(`${NOMINATIM_URL}?${params}`, {
+        headers: { "User-Agent": USER_AGENT },
+    });
+    if (!response.ok) {
+        console.error(`Nominatim HTTP ${response.status}: ${response.statusText}`);
+        return null;
+    }
+    const data = (await response.json());
+    if (data.length === 0) {
+        return null;
+    }
+    const result = data[0];
+    return {
+        lat: parseFloat(result.lat),
+        lon: parseFloat(result.lon),
+        displayName: result.display_name,
+    };
+}
+//# sourceMappingURL=nominatim.js.map

package/dist/api/overpass.d.ts

@@ -0,0 +1,11 @@
+import type { NearbyAmenity } from "../types.js";
+/** All supported amenity categories. */
+export declare const SUPPORTED_CATEGORIES: string[];
+/**
+ * Query nearby amenities around a coordinate.
+ * Returns normalized NearbyAmenity records sorted by distance.
+ */
+export declare function queryNearbyAmenities(lat: number, lon: number, radiusMeters: number, categories: string[], onWait?: () => void | Promise<void>): Promise<{
+    amenities: NearbyAmenity[];
+    error?: string;
+}>;

package/dist/api/overpass.js

@@ -0,0 +1,153 @@
+// Overpass API client — queries OpenStreetMap for nearby amenities.
+// Free, no API key. Data licensed under ODbL.
+// Rate limit: ~10,000 requests/day, max 2 concurrent queries per IP.
+// We use a single combined query per tool call to minimise requests.
+import { OVERPASS_URL, USER_AGENT } from "../config.js";
+import { overpassLimiter } from "../rate-limiter.js";
+// --- Amenity category definitions ---
+const AMENITY_TAGS = [
+    { key: "amenity", value: "school", category: "school" },
+    { key: "amenity", value: "hospital", category: "hospital" },
+    { key: "amenity", value: "clinic", category: "clinic" },
+    { key: "amenity", value: "food_court", category: "food_court" },
+    { key: "amenity", value: "marketplace", category: "marketplace" },
+    { key: "amenity", value: "pharmacy", category: "pharmacy" },
+    { key: "leisure", value: "park", category: "park" },
+    { key: "railway", value: "station", category: "mrt" },
+    { key: "highway", value: "bus_stop", category: "bus_stop" },
+    { key: "shop", value: "supermarket", category: "supermarket" },
+];
+const NODE_ONLY_CATEGORIES = new Set(["bus_stop", "mrt", "pharmacy"]);
+// --- Distance calculation ---
+/** Haversine distance in meters between two lat/lng points. */
+function haversineMeters(lat1, lon1, lat2, lon2) {
+    const R = 6371000;
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLon = toRad(lon2 - lon1);
+    const a = Math.sin(dLat / 2) ** 2 +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+    return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+// --- Query builder ---
+function buildQuery(lat, lon, radiusMeters, categories) {
+    const around = `around:${radiusMeters},${lat},${lon}`;
+    const categorySet = new Set(categories);
+    const parts = [];
+    for (const tag of AMENITY_TAGS) {
+        if (!categorySet.has(tag.category))
+            continue;
+        parts.push(`  node["${tag.key}"="${tag.value}"](${around});`);
+        if (!NODE_ONLY_CATEGORIES.has(tag.category)) {
+            parts.push(`  way["${tag.key}"="${tag.value}"](${around});`);
+            if (tag.category === "park") {
+                parts.push(`  relation["${tag.key}"="${tag.value}"](${around});`);
+            }
+        }
+    }
+    return `[out:json][timeout:60];\n(\n${parts.join("\n")}\n);\nout center body;`;
+}
+// --- Category extraction ---
+function extractCategory(tags) {
+    for (const tag of AMENITY_TAGS) {
+        if (tags[tag.key] === tag.value)
+            return tag.category;
+    }
+    return "other";
+}
+function extractAddress(tags) {
+    const parts = [];
+    if (tags["addr:housenumber"])
+        parts.push(tags["addr:housenumber"]);
+    if (tags["addr:street"])
+        parts.push(tags["addr:street"]);
+    if (tags["addr:postcode"])
+        parts.push(`Singapore ${tags["addr:postcode"]}`);
+    return parts.length > 0 ? parts.join(" ") : null;
+}
+// --- Public API ---
+/** All supported amenity categories. */
+export const SUPPORTED_CATEGORIES = AMENITY_TAGS.map((t) => t.category);
+/**
+ * Query nearby amenities around a coordinate.
+ * Returns normalized NearbyAmenity records sorted by distance.
+ */
+export async function queryNearbyAmenities(lat, lon, radiusMeters, categories, onWait) {
+    const query = buildQuery(lat, lon, radiusMeters, categories);
+    const MAX_RETRIES = 3;
+    let resp;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        await overpassLimiter.wait(onWait ? async () => { await onWait(); } : undefined);
+        try {
+            resp = await fetch(OVERPASS_URL, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "User-Agent": USER_AGENT,
+                },
+                body: `data=${encodeURIComponent(query)}`,
+            });
+        }
+        catch (err) {
+            if (attempt < MAX_RETRIES)
+                continue;
+            console.error(`[overpass] Network error: ${err.message}`);
+            return { amenities: [], error: "Could not reach amenity service. Retry after 30 seconds delay." };
+        }
+        if ((resp.status === 429 || resp.status === 504) && attempt < MAX_RETRIES) {
+            continue;
+        }
+        break;
+    }
+    if (!resp) {
+        return { amenities: [], error: "Network error after retries." };
+    }
+    if (resp.status === 429) {
+        return { amenities: [], error: "Service is busy. Retry after 30 seconds delay." };
+    }
+    if (!resp.ok) {
+        return { amenities: [], error: `Service returned an error (status ${resp.status}).` };
+    }
+    let data;
+    try {
+        data = (await resp.json());
+    }
+    catch {
+        return { amenities: [], error: "Invalid response from amenity service." };
+    }
+    const amenities = [];
+    const seenIds = new Set();
+    for (const el of data.elements) {
+        if (seenIds.has(el.id))
+            continue;
+        seenIds.add(el.id);
+        const tags = el.tags ?? {};
+        const name = tags.name ?? tags["name:en"] ?? "(unnamed)";
+        let elLat;
+        let elLon;
+        if (el.lat !== undefined && el.lon !== undefined) {
+            elLat = el.lat;
+            elLon = el.lon;
+        }
+        else if (el.center) {
+            elLat = el.center.lat;
+            elLon = el.center.lon;
+        }
+        if (elLat === undefined || elLon === undefined)
+            continue;
+        const category = extractCategory(tags);
+        const distance = haversineMeters(lat, lon, elLat, elLon);
+        amenities.push({
+            category,
+            name,
+            lat: elLat,
+            lon: elLon,
+            distanceMeters: Math.round(distance),
+            address: extractAddress(tags),
+            tags,
+        });
+    }
+    amenities.sort((a, b) => a.distanceMeters - b.distanceMeters);
+    return { amenities };
+}
+//# sourceMappingURL=overpass.js.map

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export declare const SERVER_NAME = "sg-property";
+export declare const SERVER_VERSION = "0.1.0";
+export declare const USER_AGENT: string;
+export declare const NOMINATIM_URL: string;
+export declare const ARCGIS_LAND_USE_URL: string;
+export declare const DATAGOV_URL: string;
+export declare const HDB_RESALE_RESOURCE_ID: string;
+export declare const OVERPASS_URL: string;
+export declare const RADIUS_MIN: number;
+export declare const RADIUS_MAX: number;
+export declare const RADIUS_DEFAULT: number;
+export declare const HDB_LIMIT_DEFAULT: number;
+export declare const ARCGIS_RESULT_LIMIT: number;
+export declare const SAMPLING_MAX_TOKENS: number;

package/dist/config.js

@@ -0,0 +1,32 @@
+// Central configuration — API URLs, defaults, and constants.
+// All endpoints are free, zero-key APIs verified working April 2026.
+function envInt(key, fallback) {
+    const val = process.env[key];
+    if (!val)
+        return fallback;
+    const parsed = parseInt(val, 10);
+    return isNaN(parsed) ? fallback : parsed;
+}
+export const SERVER_NAME = "sg-property";
+export const SERVER_VERSION = "0.1.0";
+export const USER_AGENT = process.env.USER_AGENT || "SG-Property-MCP/0.1.0";
+// Nominatim (OpenStreetMap) — geocoding
+export const NOMINATIM_URL = process.env.NOMINATIM_URL || "https://nominatim.openstreetmap.org/search";
+// URA ArcGIS — Master Plan 2019 land use spatial query
+export const ARCGIS_LAND_USE_URL = process.env.ARCGIS_LAND_USE_URL ||
+    "https://maps.ura.gov.sg/arcgis/rest/services/MP19/Updated_Landuse_gaz/MapServer/24/query";
+// data.gov.sg — HDB resale flat prices (2017 onwards)
+export const DATAGOV_URL = process.env.DATAGOV_URL || "https://data.gov.sg/api/action/datastore_search";
+export const HDB_RESALE_RESOURCE_ID = process.env.HDB_RESALE_RESOURCE_ID || "f1765b54-a209-4718-8d38-a39237f502b3";
+// Overpass API (OpenStreetMap) — nearby amenities
+export const OVERPASS_URL = process.env.OVERPASS_URL || "https://overpass-api.de/api/interpreter";
+// Radius bounds for spatial queries (meters)
+export const RADIUS_MIN = envInt("RADIUS_MIN", 10);
+export const RADIUS_MAX = envInt("RADIUS_MAX", 5000);
+export const RADIUS_DEFAULT = envInt("RADIUS_DEFAULT", 100);
+// Default result limits
+export const HDB_LIMIT_DEFAULT = envInt("HDB_LIMIT_DEFAULT", 10);
+export const ARCGIS_RESULT_LIMIT = envInt("ARCGIS_RESULT_LIMIT", 50);
+// Sampling defaults (analyze_results tool)
+export const SAMPLING_MAX_TOKENS = envInt("SAMPLING_MAX_TOKENS", 2048);
+//# sourceMappingURL=config.js.map

package/dist/formatters.d.ts

@@ -0,0 +1,7 @@
+import { LandParcel, HdbResaleRecord, NearbyAmenity } from "./types.js";
+export declare function formatLandParcelsTable(parcels: LandParcel[]): string;
+export declare function formatHdbTable(records: HdbResaleRecord[]): string;
+export declare function formatNearbyAmenityTable(records: NearbyAmenity[]): string;
+export declare function formatLandParcelsCsv(parcels: LandParcel[]): string;
+export declare function formatHdbCsv(records: HdbResaleRecord[]): string;
+export declare function formatNearbyAmenityCsv(records: NearbyAmenity[]): string;

package/dist/formatters.js

@@ -0,0 +1,93 @@
+// Formatters — markdown tables and CSV output for land use, HDB, and amenities.
+// --- Markdown tables ---
+export function formatLandParcelsTable(parcels) {
+    if (parcels.length === 0) {
+        return "No land parcels found in this area.";
+    }
+    const header = "| Land Use | Plot Ratio | Region | Planning Area | Subzone |";
+    const divider = "|---|---|---|---|---|";
+    const rows = parcels.map((p) => `| ${p.landUse} | ${p.grossPlotRatio ?? "N/A"} | ${p.region} | ${p.planningArea} | ${p.subzone} |`);
+    return [header, divider, ...rows].join("\n");
+}
+export function formatHdbTable(records) {
+    if (records.length === 0) {
+        return "No HDB resale records found.";
+    }
+    const header = "| Month | Block | Street | Type | Storey | Area (sqm) | Price (SGD) | Lease Start | Remaining Lease |";
+    const divider = "|---|---|---|---|---|---|---|---|---|";
+    const rows = records.map((r) => `| ${r.month} | ${r.block} | ${r.streetName} | ${r.flatType} | ${r.storeyRange} | ${r.floorAreaSqm} | $${r.resalePrice.toLocaleString()} | ${r.leaseCommenceDate} | ${r.remainingLease} |`);
+    return [header, divider, ...rows].join("\n");
+}
+// --- Nearby amenities ---
+const CATEGORY_LABELS = {
+    school: "School",
+    hospital: "Hospital",
+    clinic: "Clinic",
+    food_court: "Food Court / Hawker",
+    marketplace: "Market",
+    park: "Park",
+    mrt: "MRT/LRT Station",
+    bus_stop: "Bus Stop",
+    supermarket: "Supermarket",
+    pharmacy: "Pharmacy",
+};
+function formatDistance(meters) {
+    if (meters < 1000)
+        return `${meters}m`;
+    return `${(meters / 1000).toFixed(1)}km`;
+}
+export function formatNearbyAmenityTable(records) {
+    if (records.length === 0) {
+        return "No nearby amenities found matching your criteria.";
+    }
+    const header = "| Category | Name | Distance | Address |";
+    const divider = "|---|---|---|---|";
+    const rows = records.map((r) => `| ${CATEGORY_LABELS[r.category] ?? r.category} | ${r.name} | ${formatDistance(r.distanceMeters)} | ${r.address ?? "—"} |`);
+    return [header, divider, ...rows].join("\n");
+}
+// --- CSV ---
+/** Escape a value for CSV: wrap in quotes if it contains commas, quotes, or newlines. */
+function csvEscape(value) {
+    if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+export function formatLandParcelsCsv(parcels) {
+    const header = "Land Use,Plot Ratio,Region,Planning Area,Subzone";
+    const rows = parcels.map((p) => [p.landUse, p.grossPlotRatio ?? "N/A", p.region, p.planningArea, p.subzone]
+        .map(csvEscape)
+        .join(","));
+    return [header, ...rows].join("\n");
+}
+export function formatHdbCsv(records) {
+    const header = "Month,Block,Street,Flat Type,Storey Range,Floor Area (sqm),Resale Price (SGD),Flat Model,Lease Start,Remaining Lease";
+    const rows = records.map((r) => [
+        r.month,
+        r.block,
+        r.streetName,
+        r.flatType,
+        r.storeyRange,
+        r.floorAreaSqm,
+        String(r.resalePrice),
+        r.flatModel,
+        r.leaseCommenceDate,
+        r.remainingLease,
+    ]
+        .map(csvEscape)
+        .join(","));
+    return [header, ...rows].join("\n");
+}
+export function formatNearbyAmenityCsv(records) {
+    const header = "Category,Name,Distance (m),Latitude,Longitude,Address";
+    const rows = records.map((r) => [
+        CATEGORY_LABELS[r.category] ?? r.category,
+        r.name,
+        String(r.distanceMeters),
+        String(r.lat),
+        String(r.lon),
+        r.address ?? "",
+    ].map(csvEscape).join(","));
+    return [header, ...rows].join("\n");
+}
+//# sourceMappingURL=formatters.js.map

package/dist/helpers.d.ts

@@ -0,0 +1,12 @@
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { ServerRequest, ServerNotification } from "@modelcontextprotocol/sdk/types.js";
+/** Shorthand for the extra parameter that every tool handler receives. */
+export type ToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+export declare function clampRadius(value: number): number;
+/**
+ * Send a progress notification if the client requested one (via progressToken).
+ * No-op when the client didn't ask for progress — safe to call unconditionally.
+ */
+export declare function sendProgress(extra: ToolExtra, progress: number, total: number, message?: string): Promise<void>;
+/** Send an info-level log message to the client. */
+export declare function logInfo(extra: ToolExtra, data: string): Promise<void>;

package/dist/helpers.js

@@ -0,0 +1,26 @@
+// Shared helpers used across tool handlers.
+import { SERVER_NAME, RADIUS_MIN, RADIUS_MAX } from "./config.js";
+export function clampRadius(value) {
+    return Math.max(RADIUS_MIN, Math.min(RADIUS_MAX, value));
+}
+/**
+ * Send a progress notification if the client requested one (via progressToken).
+ * No-op when the client didn't ask for progress — safe to call unconditionally.
+ */
+export async function sendProgress(extra, progress, total, message) {
+    const token = extra._meta?.progressToken;
+    if (token === undefined)
+        return;
+    await extra.sendNotification({
+        method: "notifications/progress",
+        params: { progressToken: token, progress, total, message },
+    });
+}
+/** Send an info-level log message to the client. */
+export async function logInfo(extra, data) {
+    await extra.sendNotification({
+        method: "notifications/message",
+        params: { level: "info", logger: SERVER_NAME, data },
+    });
+}
+//# sourceMappingURL=helpers.js.map

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};