@cenogram/mcp-server 0.1.2 → 0.1.4

package/dist/api-client.d.ts

@@ -49,6 +49,7 @@ export interface Transaction {
     parcel_area: number | null;
     unit_function: number | null;
     parcel_id: string | null;
+    parcel_number: string | null;
     county_name: string | null;
     voivodeship_name: string | null;
     centroid: {
@@ -103,6 +104,9 @@ export interface TransactionParams {
     parcelId?: string;
     propertyType?: number;
     marketType?: number;
+    unitFunction?: number;
+    buildingType?: number;
+    mpzpDesignation?: string;
     minPrice?: number;
     maxPrice?: number;
     dateFrom?: string;
@@ -138,6 +142,9 @@ export interface SpatialSearchParams {
     };
     propertyType?: number;
     marketType?: number;
+    unitFunction?: number;
+    buildingType?: number;
+    mpzpDesignation?: string;
     minPrice?: number;
     maxPrice?: number;
     dateFrom?: string;
@@ -163,6 +170,7 @@ export interface SpatialFeatureProperties {
     city: string | null;
     district: string | null;
     parcel_area: number | null;
+    parcel_number: string | null;
 }
 export interface SpatialFeature {
     type: "Feature";
@@ -192,6 +200,9 @@ export interface CompareParams {
     districts: string;
     propertyType?: number;
     marketType?: number;
+    unitFunction?: number;
+    buildingType?: number;
+    mpzpDesignation?: string;
     minPrice?: number;
     maxPrice?: number;
     dateFrom?: string;

package/dist/api-client.js

@@ -95,6 +95,9 @@ export function getTransactions(p, apiKey) {
         parcelId: p.parcelId,
         propertyType: p.propertyType,
         marketType: p.marketType,
+        unitFunction: p.unitFunction,
+        buildingType: p.buildingType,
+        mpzpDesignation: p.mpzpDesignation,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -114,6 +117,9 @@ export function getTransactionsSummary(p, apiKey) {
         street: p.street,
         propertyType: p.propertyType,
         marketType: p.marketType,
+        unitFunction: p.unitFunction,
+        buildingType: p.buildingType,
+        mpzpDesignation: p.mpzpDesignation,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -141,6 +147,12 @@ export function searchByPolygon(p, apiKey) {
         body.propertyType = p.propertyType;
     if (p.marketType != null)
         body.marketType = p.marketType;
+    if (p.unitFunction != null)
+        body.unitFunction = p.unitFunction;
+    if (p.buildingType != null)
+        body.buildingType = p.buildingType;
+    if (p.mpzpDesignation)
+        body.mpzpDesignation = p.mpzpDesignation;
     if (p.minPrice != null)
         body.minPrice = p.minPrice;
     if (p.maxPrice != null)
@@ -166,6 +178,9 @@ export function compareLocations(p, apiKey) {
         districts: p.districts,
         propertyType: p.propertyType,
         marketType: p.marketType,
+        unitFunction: p.unitFunction,
+        buildingType: p.buildingType,
+        mpzpDesignation: p.mpzpDesignation,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,

package/dist/formatters.js

@@ -50,6 +50,8 @@ function formatTransactionCore(f) {
     parts.push(price.join(" | "));
     // Extra details
     const extra = [];
+    if (f.parcel_number)
+        extra.push(`Plot no: ${f.parcel_number}`);
     if (f.rooms != null)
         extra.push(`Rooms: ${f.rooms}`);
     if (f.floor != null)

package/dist/index.js

@@ -20,8 +20,8 @@ export function createMcpServer(apiKey) {
             "",
             "CRITICAL - District names (ALWAYS verify first):",
             "- NEVER guess district names. Call list_locations(search=\"city\") first.",
-            "- Warsaw: use district names (Mokotów, Wola, Śródmieście) - \"Warszawa\" returns 0 results",
-            "- Kraków: Kraków-Śródmieście, Kraków-Podgórze, Kraków-Krowodrza, Kraków-Nowa Huta",
+            "- Warsaw: 'Warszawa' auto-includes all 18 districts. Or use specific: Mokotów, Wola, Śródmieście",
+            "- Kraków/Łódź: 'Kraków'/'Łódź' auto-include all sub-districts. Or use specific: Kraków-Podgórze, etc.",
             "- Most cities (Gdańsk, Gdynia, Sopot, Poznań): just the city name, no sub-districts",
             "",
             "Workflows:",
@@ -49,7 +49,7 @@ async function main() {
         const { createServer } = await import("node:http");
         const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
         const port = parseInt(process.env.MCP_PORT || "3002", 10);
-        createServer(async (req, res) => {
+        const handleHttpRequest = async (req, res) => {
             try {
                 const pathname = req.url?.split("?")[0];
                 if (pathname === "/mcp") {
@@ -82,6 +82,11 @@ async function main() {
                     res.writeHead(500, { "Content-Type": "application/json" }).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null }));
                 }
             }
+        };
+        createServer((req, res) => {
+            handleHttpRequest(req, res).catch((err) => {
+                process.stderr.write(`Unhandled HTTP error: ${String(err)}\n`);
+            });
         }).listen(port, "0.0.0.0", () => {
             process.stderr.write(`MCP HTTP server on http://0.0.0.0:${port}/mcp\n`);
         });

package/dist/mappings.d.ts

@@ -2,7 +2,14 @@ export declare const PROPERTY_TYPES: Record<number, string>;
 export declare const MARKET_TYPES: Record<number, string>;
 export declare function mapPropertyType(value: string | undefined): number | undefined;
 export declare function mapMarketType(value: string | undefined): number | undefined;
+export declare const UNIT_FUNCTIONS: Record<number, string>;
+export declare function mapUnitFunction(value: string | undefined): number | undefined;
+export declare const BUILDING_TYPES: Record<number, string>;
+export declare function mapBuildingType(value: string | undefined): number | undefined;
 /** Convert lat/lng/radius to bbox [minLng, minLat, maxLng, maxLat] (lng-first!) */
 export declare function radiusKmToBbox(lat: number, lng: number, radiusKm: number): [number, number, number, number];
 /** Filter districts by location name (case-insensitive includes match) */
 export declare function filterByLocation(location: string, districts: string[]): string[];
+export declare const CITY_SUBDISTRICTS: ReadonlyMap<string, readonly string[]>;
+/** Returns sub-districts for known multi-district cities, or [district] for everything else. */
+export declare function expandDistrict(district: string): string[];

package/dist/mappings.js

@@ -29,6 +29,58 @@ export function mapMarketType(value) {
         return undefined;
     return MARKET_TYPE_MAP[value];
 }
+// ── Unit function enum maps ─────────────────────────────────────────
+export const UNIT_FUNCTIONS = {
+    1: "Residential (Mieszkalna)",
+    2: "Commercial (Handlowo-usługowa)",
+    3: "Office (Biurowa)",
+    4: "Production (Produkcyjna)",
+    5: "Garage (Garaż)",
+    6: "Other (Inne)",
+};
+const UNIT_FUNCTION_MAP = {
+    residential: 1,
+    commercial: 2,
+    office: 3,
+    production: 4,
+    garage: 5,
+    other: 6,
+};
+export function mapUnitFunction(value) {
+    if (!value)
+        return undefined;
+    return UNIT_FUNCTION_MAP[value];
+}
+// ── Building type enum maps ─────────────────────────────────────────
+export const BUILDING_TYPES = {
+    110: "Residential (Mieszkalny)",
+    121: "Commercial (Handlowo-usługowy)",
+    122: "Industrial (Przemysłowy)",
+    123: "Transport (Transportu i łączności)",
+    124: "Office (Biurowy)",
+    125: "Warehouse (Zbiorniki/Silosy/Magazyny)",
+    126: "Education/Sports (Oświaty i sportu)",
+    127: "Farm/Utility (Gospodarczy)",
+    128: "Hospital (Szpitale)",
+    129: "Other non-residential (Pozostałe niemieszkalne)",
+};
+const BUILDING_TYPE_MAP = {
+    residential: 110,
+    commercial: 121,
+    industrial: 122,
+    transport: 123,
+    office: 124,
+    warehouse: 125,
+    education_sports: 126,
+    farm_utility: 127,
+    hospital: 128,
+    other_nonresidential: 129,
+};
+export function mapBuildingType(value) {
+    if (!value)
+        return undefined;
+    return BUILDING_TYPE_MAP[value];
+}
 // ── Bbox conversion ─────────────────────────────────────────────────
 /** Convert lat/lng/radius to bbox [minLng, minLat, maxLng, maxLat] (lng-first!) */
 export function radiusKmToBbox(lat, lng, radiusKm) {
@@ -47,3 +99,23 @@ export function filterByLocation(location, districts) {
     const lower = location.toLowerCase();
     return districts.filter((d) => d.toLowerCase().includes(lower));
 }
+// ── City → sub-district expansion ───────────────────────────────────
+// Keep in sync with api/src/helpers.ts CITY_SUBDISTRICTS (ADR-003).
+// Cities: Warszawa (19), Kraków (5), Łódź (6).
+export const CITY_SUBDISTRICTS = new Map([
+    ["Warszawa", [
+            "Warszawa", "Bemowo", "Białołęka", "Bielany", "Mokotów", "Ochota",
+            "Praga-Południe", "Praga-Północ", "Rembertów", "Śródmieście", "Targówek",
+            "Ursus", "Ursynów", "Wawer", "Wesoła", "Wilanów", "Włochy", "Wola", "Żoliborz",
+        ]],
+    ["Kraków", [
+            "Kraków", "Kraków-Krowodrza", "Kraków-Nowa Huta", "Kraków-Podgórze", "Kraków-Śródmieście",
+        ]],
+    ["Łódź", [
+            "Łódź", "Łódź-Bałuty", "Łódź-Górna", "Łódź-Polesie", "Łódź-Śródmieście", "Łódź-Widzew",
+        ]],
+]);
+/** Returns sub-districts for known multi-district cities, or [district] for everything else. */
+export function expandDistrict(district) {
+    return CITY_SUBDISTRICTS.get(district)?.slice() ?? [district];
+}

package/dist/tools.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { getStats, getTransactions, getPricePerM2, getDistricts, getPriceHistogram, getTransactionsSummary, searchParcels, searchByPolygon, compareLocations, } from "./api-client.js";
 import { formatTransactionList, formatMarketOverview, formatPriceStats, formatHistogram, formatParcelResults, formatSpatialResults, formatCompareResults, } from "./formatters.js";
-import { mapPropertyType, mapMarketType, radiusKmToBbox, filterByLocation, } from "./mappings.js";
+import { mapPropertyType, mapMarketType, mapUnitFunction, mapBuildingType, radiusKmToBbox, filterByLocation, expandDistrict, CITY_SUBDISTRICTS, } from "./mappings.js";
 // ── Helpers ─────────────────────────────────────────────────────────
 function textResponse(text) {
     return { content: [{ type: "text", text }] };
@@ -32,11 +32,17 @@ export function registerTools(server, apiKey) {
 Returns transaction details: address, date, price, area, price/m², property type.
 Use list_locations first to find valid location names.
 Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.`, {
-        location: z.string().optional().describe("Location name - city (e.g. 'Kraków', 'Gdańsk') or district (e.g. 'Mokotów', 'Śródmieście'). For Warsaw, use district names (Mokotów, Wola, etc.) - 'Warszawa' won't match. Use list_locations to find valid names."),
+        location: z.string().optional().describe("Location name - city (e.g. 'Warszawa', 'Kraków', 'Gdańsk') or district (e.g. 'Mokotów', 'Kraków-Podgórze'). 'Warszawa', 'Kraków', 'Łódź' auto-expand to all sub-districts. Use list_locations to find valid names."),
         propertyType: z.enum(["land", "building", "developed_land", "unit"]).optional()
             .describe("Property type filter"),
         marketType: z.enum(["primary", "secondary"]).optional()
             .describe("Market type: primary (developer) or secondary (resale)"),
+        unitFunction: z.enum(["residential", "commercial", "office", "production", "garage", "other"]).optional()
+            .describe("Unit/apartment function filter"),
+        buildingType: z.enum(["residential", "commercial", "industrial", "transport", "office", "warehouse", "education_sports", "farm_utility", "hospital", "other_nonresidential"]).optional()
+            .describe("Building type filter (PKOB classification)"),
+        mpzpDesignation: z.string().optional()
+            .describe("MPZP zoning designation filter (exact match, e.g. 'budownictwoMieszkanioweWielorodzinne', 'terenObiektowProdukcyjnychSkladowIMagazynow')"),
         minPrice: z.number().optional().describe("Minimum price in PLN"),
         maxPrice: z.number().optional().describe("Maximum price in PLN"),
         dateFrom: z.string().optional().describe("Start date (YYYY-MM-DD)"),
@@ -60,6 +66,9 @@ Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.`, {
             district: params.location,
             propertyType: mapPropertyType(params.propertyType),
             marketType: mapMarketType(params.marketType),
+            unitFunction: mapUnitFunction(params.unitFunction),
+            buildingType: mapBuildingType(params.buildingType),
+            mpzpDesignation: params.mpzpDesignation,
             minPrice: params.minPrice,
             maxPrice: params.maxPrice,
             dateFrom: params.dateFrom,
@@ -83,14 +92,20 @@ Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.`, {
     // ── Tool 2: get_price_statistics ────────────────────────────────────
     server.tool("get_price_statistics", `Get price per m² statistics by location for residential apartments in Poland.
 Note: only covers residential units (lokale mieszkalne). For other property types, use search_transactions.
-For Warsaw: use district names (Mokotów, Wola) - 'Warszawa' won't match any results.`, {
-        location: z.string().optional().describe("Filter by location name (case-insensitive partial match). E.g. 'Kraków' matches 'Kraków-Podgórze', 'Kraków-Śródmieście', etc. Omit for all Poland."),
+'Warszawa'/'Kraków'/'Łódź' auto-expand to all sub-districts (Warszawa=19, Kraków=5, Łódź=6). Other names use partial match.`, {
+        location: z.string().optional().describe("Filter by location name. 'Warszawa'/'Kraków'/'Łódź' auto-expand to all sub-districts. Other names use case-insensitive partial match (e.g. 'Wrocł' matches 'Wrocław'). Omit for all Poland."),
     }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
         requireApiKey(apiKey);
         const { data: allRows, creditInfo } = await getPricePerM2(apiKey);
         let rows = allRows;
         if (params.location) {
-            rows = rows.filter((r) => filterByLocation(params.location, [r.district]).length > 0);
+            if (CITY_SUBDISTRICTS.has(params.location)) {
+                const allowed = new Set(expandDistrict(params.location));
+                rows = rows.filter((r) => allowed.has(r.district));
+            }
+            else {
+                rows = rows.filter((r) => filterByLocation(params.location, [r.district]).length > 0);
+            }
         }
         return textResponse(formatPriceStats(rows, params.location) + formatCreditFooter(creditInfo));
     }));
@@ -109,7 +124,8 @@ Useful for understanding the overall market price structure in Poland.`, {
     // ── Tool 4: search_by_area ──────────────────────────────────────────
     server.tool("search_by_area", `Search real estate transactions within a geographic radius.
 Provide latitude/longitude coordinates and a radius in km.
-Example: find apartment sales within 2km of Warsaw's Palace of Culture (lat 52.2317, lng 21.0060).`, {
+Example: find apartment sales within 2km of Warsaw's Palace of Culture (lat 52.2317, lng 21.0060).
+Area filters (minArea/maxArea) work for all propertyType values via COALESCE(usable_area_m2, parcel_area).`, {
         latitude: z.number().min(49).max(55)
             .describe("Latitude (Poland range: 49-55)"),
         longitude: z.number().min(14).max(25)
@@ -120,8 +136,16 @@ Example: find apartment sales within 2km of Warsaw's Palace of Culture (lat 52.2
             .describe("Property type filter"),
         marketType: z.enum(["primary", "secondary"]).optional()
             .describe("Market type filter"),
+        unitFunction: z.enum(["residential", "commercial", "office", "production", "garage", "other"]).optional()
+            .describe("Unit/apartment function filter"),
+        buildingType: z.enum(["residential", "commercial", "industrial", "transport", "office", "warehouse", "education_sports", "farm_utility", "hospital", "other_nonresidential"]).optional()
+            .describe("Building type filter (PKOB classification)"),
         minPrice: z.number().optional().describe("Minimum price in PLN"),
         maxPrice: z.number().optional().describe("Maximum price in PLN"),
+        minArea: z.number().optional()
+            .describe("Minimum area in m² (usable_area_m2 for units, parcel_area for land)"),
+        maxArea: z.number().optional()
+            .describe("Maximum area in m²"),
         dateFrom: z.string().optional().describe("Start date (YYYY-MM-DD)"),
         dateTo: z.string().optional().describe("End date (YYYY-MM-DD)"),
         limit: z.number().min(1).max(50).default(20)
@@ -133,8 +157,12 @@ Example: find apartment sales within 2km of Warsaw's Palace of Culture (lat 52.2
             bbox: bbox.join(","),
             propertyType: mapPropertyType(params.propertyType),
             marketType: mapMarketType(params.marketType),
+            unitFunction: mapUnitFunction(params.unitFunction),
+            buildingType: mapBuildingType(params.buildingType),
             minPrice: params.minPrice,
             maxPrice: params.maxPrice,
+            minArea: params.minArea,
+            maxArea: params.maxArea,
             dateFrom: params.dateFrom,
             dateTo: params.dateTo,
             limit: params.limit,
@@ -213,6 +241,12 @@ Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21
             .describe("Property type filter"),
         marketType: z.enum(["primary", "secondary"]).optional()
             .describe("Market type filter"),
+        unitFunction: z.enum(["residential", "commercial", "office", "production", "garage", "other"]).optional()
+            .describe("Unit/apartment function filter"),
+        buildingType: z.enum(["residential", "commercial", "industrial", "transport", "office", "warehouse", "education_sports", "farm_utility", "hospital", "other_nonresidential"]).optional()
+            .describe("Building type filter (PKOB classification)"),
+        mpzpDesignation: z.string().optional()
+            .describe("MPZP zoning designation filter (exact match)"),
         minPrice: z.number().optional().describe("Minimum price in PLN"),
         maxPrice: z.number().optional().describe("Maximum price in PLN"),
         dateFrom: z.string().optional().describe("Start date (YYYY-MM-DD)"),
@@ -229,6 +263,9 @@ Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21
             polygon: params.polygon,
             propertyType: mapPropertyType(params.propertyType),
             marketType: mapMarketType(params.marketType),
+            unitFunction: mapUnitFunction(params.unitFunction),
+            buildingType: mapBuildingType(params.buildingType),
+            mpzpDesignation: params.mpzpDesignation,
             minPrice: params.minPrice,
             maxPrice: params.maxPrice,
             dateFrom: params.dateFrom,
@@ -252,6 +289,12 @@ Example: compare Mokotów, Wola, Ursynów for apartments.`, {
             .describe("Property type filter (recommended - API requires at least one filter)"),
         marketType: z.enum(["primary", "secondary"]).optional()
             .describe("Market type filter"),
+        unitFunction: z.enum(["residential", "commercial", "office", "production", "garage", "other"]).optional()
+            .describe("Unit/apartment function filter"),
+        buildingType: z.enum(["residential", "commercial", "industrial", "transport", "office", "warehouse", "education_sports", "farm_utility", "hospital", "other_nonresidential"]).optional()
+            .describe("Building type filter (PKOB classification)"),
+        mpzpDesignation: z.string().optional()
+            .describe("MPZP zoning designation prefix filter (e.g. 'terenRolniczy', 'budownictwoMieszkanioweJednorodzinne', 'budownictwoMieszkanioweWielorodzinne')"),
         minPrice: z.number().optional().describe("Minimum price in PLN"),
         maxPrice: z.number().optional().describe("Maximum price in PLN"),
         dateFrom: z.string().optional().describe("Start date (YYYY-MM-DD)"),
@@ -265,6 +308,9 @@ Example: compare Mokotów, Wola, Ursynów for apartments.`, {
             districts: params.districts,
             propertyType: mapPropertyType(params.propertyType),
             marketType: mapMarketType(params.marketType),
+            unitFunction: mapUnitFunction(params.unitFunction),
+            buildingType: mapBuildingType(params.buildingType),
+            mpzpDesignation: params.mpzpDesignation,
             minPrice: params.minPrice,
             maxPrice: params.maxPrice,
             dateFrom: params.dateFrom,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cenogram/mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "MCP Server for Polish real estate transaction data (7M+ transactions from RCN)",
   "type": "module",
   "bin": {
@@ -10,23 +10,37 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
-    "prepublishOnly": "npm run build"
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "check": "tsc --noEmit && eslint .",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.13.0",
     "@types/node": "^22.0.0",
+    "eslint": "^9.13.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "typescript-eslint": "^8.11.0",
+    "vitest": "^4.1.4"
   },
   "mcpName": "pl.cenogram/mcp-server",
-  "keywords": ["mcp", "real-estate", "poland", "rcn", "nieruchomosci", "property", "transactions"],
+  "keywords": [
+    "mcp",
+    "real-estate",
+    "poland",
+    "rcn",
+    "nieruchomosci",
+    "property",
+    "transactions"
+  ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"