@cenogram/mcp-server 0.5.0 → 0.11.0

package/README.md

@@ -4,9 +4,9 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**Polish Real Estate Transaction Data for AI**
+**Polish Real Estate Transaction & Parcel Data for AI**
 
-MCP server for Polish real estate data. Access 8M+ real estate transactions from the national Registry of Prices and Values (Rejestr Cen Nieruchomosci, RCN) directly from Claude, Cursor, or any MCP-compatible AI assistant.
+MCP server for Polish real estate data. Access 8M+ real estate transactions from the national Registry of Prices and Values (Rejestr Cen Nieruchomosci, RCN) - prices from notarial deeds, not listings - directly from Claude, Cursor, ChatGPT, Grok, or any MCP-compatible AI assistant. Beyond transaction prices, the server resolves cadastral parcels and adds per-parcel context: zoning, flood and landslide risk, heritage register, building permits and construction activity, public transport access, agricultural land classification, surrounding land use, nature - nearby forest and overlapping protected areas - what lies underground (mining terrains and major groundwater reservoirs), the land-use and soil-quality classification, and road access.
 
 Data source: Polish national RCN registry (Rejestr Cen Nieruchomosci) | Platform: [cenogram.pl](https://cenogram.pl?src=mcpstdio)
 
@@ -18,6 +18,18 @@ Data source: Polish national RCN registry (Rejestr Cen Nieruchomosci) | Platform
 
 Manage your keys at [cenogram.pl/ustawienia](https://cenogram.pl/ustawienia).
 
+### Free tier
+
+New accounts start with 1,000 tokens and a 14-day trial of the Standard plan. After that the key keeps
+working on 50 tokens a week - the balance is restored to 50 every 7 days rather than accumulating -
+with no expiry date and no card.
+
+A call costs 1 token for statistics, reference data, parcel identity and municipal context; 2 for a
+transaction search, a price histogram or a list of the parcels in an area; 4 for one context layer of
+a parcel or transaction; 5 for spatial search, parcel outlines, valuation and a multi-district
+comparison; 45 for `get_parcel_report`, which returns every layer at once. Location catalogues are
+free. Paid plans raise the allowance - see [cenogram.pl/api](https://cenogram.pl/api?src=mcpstdio#cennik).
+
 ## Installation
 
 Pick your client. All options below use the hosted server - no local install needed (except npx/stdio).
@@ -193,7 +205,8 @@ You can also use the `--http` CLI flag instead of `MCP_TRANSPORT=http`.
 **Polish:**
 - "Jaka jest mediana cen mieszkan w Krakowie w 2025?"
 - "Pokaz transakcje z ulicy Pulawskiej 15 na Mokotowie"
-- "Znajdz transakcje na dzialce 146518_8.0108.27"
+- "Znajdz transakcje na dzialce 126104_9.0015.201"
+- "Sprawdz plan miejscowy i ryzyko powodziowe dla dzialki 126104_9.0015.201"
 - "Znajdz transakcje gruntow w promieniu 5km od centrum Wroclawia powyzej 500 000 PLN"
 - "Porownaj ceny mieszkan na Mokotowie i Woli"
 - "Pokaz rozklad cen nieruchomosci w Polsce"
@@ -201,7 +214,8 @@ You can also use the `--http` CLI flag instead of `MCP_TRANSPORT=http`.
 **English:**
 - "What's the median apartment price in Krakow in 2025?"
 - "Show transactions at Pulawska 15 in Mokotow"
-- "Find all transactions on parcel 146502_8.0901.12 and then search nearby"
+- "Find all transactions on parcel 126104_9.0015.201 and then search nearby"
+- "Check the zoning and flood risk for parcel 126104_9.0015.201"
 - "Find land transactions within 5km of Wroclaw center above 500,000 PLN"
 - "Compare apartment prices in Mokotow and Wola districts"
 - "Show the price distribution of real estate in Poland"
@@ -213,15 +227,16 @@ You can also use the `--http` CLI flag instead of `MCP_TRANSPORT=http`.
 | `search_transactions` | Search transactions with filters | location, street, buildingNumber, parcelId, propertyType, marketType, price/date/area range |
 | `get_price_statistics` | Price/m2 stats by location (residential only) | location (optional) |
 | `get_price_distribution` | Price histogram | bins, maxPrice |
-| `search_by_area` | Search by geographic radius | latitude, longitude, radiusKm |
+| `search_by_area` | Search transactions by geographic radius | latitude, longitude, radiusKm |
 | `get_market_overview` | Database overview and stats | (none) |
 | `list_locations` | List available locations | search (optional) |
 | `search_parcels` | Search parcels by cadastral ID prefix | q (parcel ID prefix, min 3 chars) |
-| `search_by_polygon` | Search within a GeoJSON polygon | polygon, propertyType, dateFrom/dateTo |
+| `list_parcels_in_area` | List the cadastral parcels in an area - light list or full outlines | teryt, location, bbox, lat + lng + radiusKm, or polygon; includeGeometry, minArea/maxArea, street/buildingNumber, cursor |
+| `search_by_polygon` | Search transactions within a GeoJSON polygon | polygon, propertyType, dateFrom/dateTo |
 | `compare_locations` | Compare stats across 2-5 districts | districts (comma-separated), propertyType |
 | `get_building_breakdown` | Per-building breakdown for one transaction (footprint, storeys, est. floor area) | transaction_id (UUID from a search result) |
-| `get_parcel_report` | Composite dossier for one parcel: core, 9 enrichment layers, transaction history, local price context and municipal context | parcelId (cadastral id or UUID) |
-| `resolve_parcel` | Resolve a cadastral parcel identifier to its canonical record | parcelId or q (id prefix), or lat + lng |
+| `get_parcel_report` | Composite dossier for one parcel: core, 13 enrichment layers, transaction history, local price context and municipal context | parcelId (cadastral id or UUID) |
+| `resolve_parcel` | Resolve a parcel to its cadastral identity | parcelId, q (full cadastral id or 'locality + parcel number' - not a street address), or lat + lng |
 | `get_demographics` | Population and demographic context for a location | location or teryt, year (or yearFrom/yearTo), category |
 | `get_infrastructure_signals` | Municipal infrastructure signals (tenders, utilities, capital spending) | location or teryt |
 | `estimate_value` | Comparable-sales value estimate for a property | area, plus lat + lng or parcelId; rooms, market |
@@ -233,6 +248,9 @@ You can also use the `--http` CLI flag instead of `MCP_TRANSPORT=http`.
 | `get_transaction_permits` | Building permits recorded for the property | transaction_id |
 | `get_transaction_planning` | Local zoning and planning status for the property | transaction_id |
 | `get_transaction_farmland` | Agricultural land-use classification for the property | transaction_id |
+| `get_transaction_nature` | Nearby forest and overlapping protected natural areas for the property | transaction_id |
+| `get_transaction_subsurface` | Mining terrains and major groundwater reservoirs under the property | transaction_id |
+| `get_transaction_roads` | Geometric evidence of road access for the property (distances, road class, access indicator) | transaction_id |
 
 ### Location naming
 
@@ -264,12 +282,24 @@ Results include parcel IDs and GPS coordinates, enabling multi-step research:
 
 This mimics how a property appraiser finds comparable transactions for valuation reports.
 
+Starting from the land rather than from a deed is a different route:
+
+```
+1. List the parcels     -> list_parcels_in_area(location="Wawer", minArea=800)
+2. Draw the ones you want -> list_parcels_in_area(bbox="21.10,52.20,21.14,52.23", includeGeometry=true)
+3. Open one in full     -> get_parcel_report(parcelId="146518_8.0108.27")
+```
+
+Step 1 pages by cursor; step 2 is capped and usually truncated, so narrow the box rather than reading
+a truncated answer as the parcel list of the area.
+
 ## Data
 
 - **8M+ transactions** from all of Poland (380 counties)
 - **Date range:** 2003 - present
 - **Source:** Polish national RCN registry (Rejestr Cen Nieruchomosci)
 - **Refresh:** periodic updates from RCN
+- **Per-parcel context:** zoning, flood and landslide risk, heritage register, building permits and construction activity, transit access, agricultural land use, surroundings, nature (nearby forest and protected areas), subsurface (mining terrains and major groundwater reservoirs), land-use and soil-quality classification, and road access - addressable by cadastral ID
 
 ## Troubleshooting
 
@@ -281,6 +311,8 @@ This mimics how a property appraiser finds comparable transactions for valuation
 
 **401 Unauthorized (HTTP mode)** - The `Authorization` header must be `Bearer cngrm_...` (with the `Bearer` prefix). Double-check that the full API key is included, not just the prefix.
 
+**402 Payment Required** - The account is out of tokens. On a free account the response says the date from which the balance is back at its weekly 50; the key and the connection stay valid until then. A paid plan lifts the limit - see [cenogram.pl/api](https://cenogram.pl/api?src=mcpstdio#cennik).
+
 ## Development
 
 ```bash

package/dist/api-client.d.ts

@@ -1,3 +1,4 @@
+import { type AuthMode } from "./error-messages.js";
 export interface StatsResponse {
     counts: {
         transactions: number;
@@ -338,6 +339,7 @@ export declare function getInfrastructureSignals(params: {
 export interface CreditInfo {
     balance: number;
     cost: number;
+    refunded?: number;
 }
 export interface ApiResponse<T> {
     data: T;
@@ -351,6 +353,19 @@ export declare function decodeOAuthCtx(key: string): {
 } | null;
 export declare function parseRetryAfterSeconds(headerValue: string | null | undefined): number | null;
 export declare function formatRetryAfter(seconds: number): string;
+export declare class ApiHttpError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly authMode: AuthMode;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(message: string, opts: {
+        status: number;
+        code?: string | undefined;
+        authMode: AuthMode;
+        retryAfterSeconds?: number | undefined;
+    });
+}
+export declare function isExpectedApiError(error: unknown): boolean;
 export declare function fetchApi<T>(path: string, params?: Record<string, string>, apiKey?: string): Promise<ApiResponse<T>>;
 export declare function fetchApiPost<T>(path: string, body: unknown, apiKey?: string): Promise<ApiResponse<T>>;
 export declare function getStats(apiKey?: string): Promise<ApiResponse<StatsResponse>>;
@@ -379,6 +394,10 @@ export interface TransactionParams {
     floodRisk?: string;
     heritageStatus?: string;
     landslideRisk?: string;
+    landUse?: string;
+    buildingStoreys?: string;
+    minFootprintArea?: number;
+    maxFootprintArea?: number;
     limit?: number;
     page?: number;
     sort?: string;
@@ -405,6 +424,51 @@ export declare function getPriceSpread(params: {
 export declare function getPriceSpreadLocations(params: {
     search?: string;
 }, apiKey?: string): Promise<ApiResponse<PriceSpreadLocationsResponse>>;
+export interface FloodRiskResponse {
+    location: LocationRef;
+    metric: "flood_exposure_share";
+    result: {
+        flood_share_pct: number | null;
+        by_severity: {
+            low: number | null;
+            medium: number | null;
+            high: number | null;
+        };
+    };
+    inputs: {
+        assessed_sample_n: number | null;
+        window: "all_time";
+    };
+    quality: {
+        coverage: "full" | "low_sample" | "suppressed";
+        confidence: "high" | "low";
+        as_of: string | null;
+        stale: boolean;
+        notes: string[];
+    };
+}
+export interface FloodRiskLocation {
+    location: string;
+    county_code: string;
+    voivodeship: string;
+    type: "city" | "county";
+    assessed_sample_n: number;
+    confidence: "high" | "low";
+}
+export interface FloodRiskLocationsResponse {
+    data: FloodRiskLocation[];
+    meta: {
+        total: number;
+        snapshot_date: string | null;
+    };
+}
+export declare function getFloodRisk(params: {
+    location?: string;
+    teryt?: string;
+}, apiKey?: string): Promise<ApiResponse<FloodRiskResponse>>;
+export declare function getFloodRiskLocations(params: {
+    search?: string;
+}, apiKey?: string): Promise<ApiResponse<FloodRiskLocationsResponse>>;
 export interface ValuationComparable {
     distance_m: number;
     transaction_date: string;
@@ -475,8 +539,13 @@ export interface LocationItem {
     name: string;
     typeName: string | null;
     level: "voivodeship" | "county" | "municipality" | "precinct";
+    parent_name: string | null;
+}
+export interface LocationSearchItem extends LocationItem {
+    rcn_district?: boolean;
 }
 export declare function getLocations(parent?: string, apiKey?: string): Promise<ApiResponse<LocationItem[]>>;
+export declare function searchLocations(q: string, apiKey?: string): Promise<ApiResponse<LocationSearchItem[]>>;
 export declare function getPriceHistogram(bins?: number, max?: number, apiKey?: string): Promise<ApiResponse<HistogramBin[]>>;
 export interface ParcelSearchResult {
     parcel_id?: string;
@@ -487,8 +556,102 @@ export interface ParcelSearchResult {
 }
 export interface ParcelSearchResponse {
     results: ParcelSearchResult[];
+    corpus_coverage?: CorpusCoverage | null;
 }
 export declare function searchParcels(q: string, limit?: number, apiKey?: string): Promise<ApiResponse<ParcelSearchResponse>>;
+export interface ParcelListRow {
+    id: string;
+    parcel_id: string | null;
+    parcel_key: string | null;
+    district: string | null;
+    lat: number | null;
+    lng: number | null;
+    street?: string | null;
+    building_number?: string | null;
+    address_source?: "rcn" | "approx_high" | "approx_low" | "none" | null;
+}
+export interface CorpusCoverage {
+    basis: string;
+    held_parcels: number | null;
+    source_parcels: number | null;
+    held_pct: number | null;
+    counties: number | null;
+    as_of: string | null;
+    note: string;
+}
+export interface ParcelListResponse {
+    data: ParcelListRow[];
+    pagination: {
+        limit: number;
+        has_more: boolean;
+        next_cursor?: string;
+    };
+    corpus_coverage?: CorpusCoverage | null;
+    suggestions?: {
+        streets?: string[];
+        building_numbers?: string[];
+    };
+    hint?: string;
+}
+export interface ParcelListParams {
+    location?: string;
+    teryt?: string;
+    bbox?: string;
+    lat?: number;
+    lng?: number;
+    radiusKm?: number;
+    minArea?: number;
+    maxArea?: number;
+    street?: string;
+    buildingNumber?: string;
+    limit?: number;
+    cursor?: string;
+}
+export declare function listParcels(p: ParcelListParams, apiKey?: string): Promise<ApiResponse<ParcelListResponse>>;
+export interface StreetListRow {
+    street: string;
+    address_source: "rcn" | "approx";
+}
+export interface StreetListResponse {
+    data: StreetListRow[];
+    scope: {
+        teryt: string;
+        resolved_from: "teryt" | "location";
+    };
+    pagination: {
+        limit: number;
+        has_more: boolean;
+    };
+}
+export declare function getStreets(scope: {
+    q: string;
+    teryt?: string;
+    location?: string;
+}, apiKey?: string): Promise<ApiResponse<StreetListResponse>>;
+export interface ParcelFeature {
+    type: "Feature";
+    geometry: {
+        type: string;
+        coordinates: unknown;
+    } | null;
+    properties: {
+        id: string;
+        parcel_id: string | null;
+        parcel_key: string | null;
+        district: string | null;
+    };
+}
+export interface ParcelFeatureCollection {
+    type: "FeatureCollection";
+    truncated: boolean;
+    features: ParcelFeature[];
+    corpus_coverage?: CorpusCoverage | null;
+}
+export declare function getParcelsMap(bbox: string, limit: number | undefined, apiKey?: string): Promise<ApiResponse<ParcelFeatureCollection>>;
+export declare function searchParcelsByPolygon(polygon: {
+    type: "Polygon";
+    coordinates: number[][][];
+}, limit: number | undefined, apiKey?: string): Promise<ApiResponse<ParcelFeatureCollection>>;
 export interface ParcelResolveMatch {
     id: string;
     parcel_id: string | null;
@@ -511,10 +674,11 @@ export interface ParcelResolveResponse {
         lat?: number;
         lng?: number;
     };
-    coverage: "covered" | "not_covered";
+    coverage: "covered" | "not_covered" | "not_computed";
     as_of: string | null;
     matches: ParcelResolveMatch[];
     truncated: boolean;
+    corpus_coverage?: CorpusCoverage | null;
 }
 export interface ResolveParcelParams {
     q?: string;
@@ -606,12 +770,16 @@ export interface ParcelReportResponse {
         flood: ReportSection;
         heritage: ReportSection;
         landslide: ReportSection;
+        subsurface: ReportSection;
         surroundings: ReportSection;
         transit: ReportSection;
         planning: ReportSection;
         buildings: ReportSection;
         permits: ReportSection;
         farmland: ReportSection;
+        land_class: ReportSection;
+        nature: ReportSection;
+        roads: ReportSection;
         market_context: ReportMarketContext;
         location_context: ReportLocationContext;
     };
@@ -623,6 +791,24 @@ export interface ParcelReportResponse {
     note?: string | null;
 }
 export declare function getParcelReport(parcelKey: string, apiKey?: string): Promise<ApiResponse<ParcelReportResponse>>;
+export interface ParcelLandClassResponse {
+    parcel: {
+        id: string | null;
+        parcel_id: string | null;
+        parcel_key: string | null;
+    };
+    coverage: string;
+    as_of: string | null;
+    use_codes: string[];
+    use_names: string[];
+    soil_classes: string[];
+    protected_class_present: boolean;
+    in_city: boolean | null;
+    legal_note: string | null;
+    legal_state_as_of: string | null;
+    note?: string | null;
+}
+export declare function getParcelLandClass(parcelKey: string, apiKey?: string): Promise<ApiResponse<ParcelLandClassResponse>>;
 export interface SpatialSearchParams {
     polygon: {
         type: "Polygon";
@@ -645,6 +831,10 @@ export interface SpatialSearchParams {
     transactionType?: string;
     rooms?: string;
     floor?: string;
+    landUse?: string;
+    buildingStoreys?: string;
+    minFootprintArea?: number;
+    maxFootprintArea?: number;
     limit?: number;
 }
 export interface SpatialFeatureProperties {
@@ -737,6 +927,19 @@ export interface CompareParams {
     include?: string;
 }
 export declare function compareLocations(p: CompareParams, apiKey?: string): Promise<ApiResponse<CompareResponse>>;
+export interface BuildingAgeEstimate {
+    status: "estimated" | "older_than_register" | "ambiguous_permits" | "ambiguous_buildings" | "ambiguous_both" | "no_parcel_key" | "not_applicable" | "not_computed";
+    year_from: number | null;
+    year_to: number | null;
+    year_point: number | null;
+    basis: string | null;
+    basis_year: number | null;
+    match_rule: string | null;
+    confidence: string | null;
+    offset_model: string | null;
+    last_works_year: number | null;
+    note: string;
+}
 export interface BuildingBreakdownRow {
     building_type: number | null;
     footprint_area_m2: number | null;
@@ -745,6 +948,7 @@ export interface BuildingBreakdownRow {
     storeys: number | null;
     est_total_area_m2: number | null;
     match_confidence: string | null;
+    age_estimate?: BuildingAgeEstimate;
 }
 export interface BuildingBreakdownResponse {
     data: BuildingBreakdownRow[];
@@ -806,6 +1010,25 @@ export interface LandslideBreakdownResponse {
     data: LandslideBreakdownRow[];
     truncated: boolean;
 }
+export interface NatureArea {
+    form: string | null;
+    name: string | null;
+    overlap_pct: number | string | null;
+}
+export interface NatureBreakdownRow {
+    forest_distance_m: number | null;
+    forest_overlap_pct: number | string | null;
+    protection_rank: number | null;
+    building_restriction: "statutory_ban" | "conditional" | null;
+    protected_overlap_pct: number | string | null;
+    protected_forms: string[] | null;
+    protected_areas: NatureArea[] | null;
+}
+export interface NatureBreakdownResponse {
+    data: NatureBreakdownRow[];
+    truncated: boolean;
+    coverage?: "covered" | "covered_no_data" | "not_covered";
+}
 export interface TransitBreakdownRow {
     rail_distance_m: number | null;
     rail_stop_name: string | null;
@@ -841,6 +1064,41 @@ export interface PermitsResponse {
 }
 export declare function getTransactionHeritage(transactionId: string, apiKey?: string): Promise<ApiResponse<HeritageBreakdownResponse>>;
 export declare function getTransactionLandslide(transactionId: string, apiKey?: string): Promise<ApiResponse<LandslideBreakdownResponse>>;
+export declare function getTransactionNature(transactionId: string, apiKey?: string): Promise<ApiResponse<NatureBreakdownResponse>>;
+export interface SubsurfaceMiningTerrain {
+    name: string | null;
+    status: "active" | "former" | string | null;
+    mineral_class: "subsidence" | "surface" | "fluid" | "other" | string | null;
+    oversight_authority: string | null;
+    valid_until: string | null;
+    revoked_on: string | null;
+    overlap_pct: number | string | null;
+}
+export interface SubsurfaceGroundwaterBody {
+    number: number | null;
+    name: string | null;
+    documentation_status: "documented" | "undocumented" | string | null;
+    documented_year: number | null;
+    depth_from_m: number | null;
+    medium_type: string | null;
+    overlap_pct: number | string | null;
+}
+export interface SubsurfaceBreakdownRow {
+    mining_status: "active" | "former" | string | null;
+    mineral_class: "subsidence" | "surface" | "fluid" | "other" | string | null;
+    mining_overlap_pct: number | string | null;
+    mining_terrains: SubsurfaceMiningTerrain[] | null;
+    mining_terrains_capped?: boolean | null;
+    groundwater_status: "documented" | "undocumented" | string | null;
+    groundwater_overlap_pct: number | string | null;
+    groundwater_bodies: SubsurfaceGroundwaterBody[] | null;
+    groundwater_bodies_capped?: boolean | null;
+}
+export interface SubsurfaceBreakdownResponse {
+    data: SubsurfaceBreakdownRow[];
+    truncated: boolean;
+}
+export declare function getTransactionSubsurface(transactionId: string, apiKey?: string): Promise<ApiResponse<SubsurfaceBreakdownResponse>>;
 export interface SurroundingsRow {
     assessed: boolean;
     cemetery_distance_m: number | string | null;
@@ -849,12 +1107,32 @@ export interface SurroundingsRow {
     industrial_area_distance_m: number | string | null;
     industrial_plant_distance_m: number | string | null;
     livestock_farm_distance_m: number | string | null;
+    power_line_hv_distance_m?: number | string | null;
+    power_line_ehv_distance_m?: number | string | null;
 }
 export interface SurroundingsResponse {
     data: SurroundingsRow[];
     truncated?: boolean;
 }
 export declare function getTransactionSurroundings(transactionId: string, apiKey?: string): Promise<ApiResponse<SurroundingsResponse>>;
+export interface RoadsBreakdownRow {
+    assessed: boolean;
+    access_indicator: "likely" | "uncertain" | "unlikely" | string | null;
+    access_rule_version: number | null;
+    public_road_distance_m: number | string | null;
+    public_road_edge_distance_m: number | string | null;
+    public_road_category: "national" | "voivodeship" | "county" | "municipal" | string | null;
+    public_road_class: "motorway" | "expressway" | "main_accelerated" | "main" | "collector" | "local" | "access" | "other" | string | null;
+    public_road_at_grade: boolean | null;
+    any_road_distance_m: number | string | null;
+    major_road_distance_m: number | string | null;
+    source_as_of: string | null;
+}
+export interface RoadsBreakdownResponse {
+    data: RoadsBreakdownRow[];
+    truncated?: boolean;
+}
+export declare function getTransactionRoads(transactionId: string, apiKey?: string): Promise<ApiResponse<RoadsBreakdownResponse>>;
 export declare function getTransactionTransit(transactionId: string, apiKey?: string): Promise<ApiResponse<TransitBreakdownResponse>>;
 export declare function getTransactionPermits(transactionId: string, apiKey?: string): Promise<ApiResponse<PermitsResponse>>;
 export interface PlanningRow {