@cenogram/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cenogram (cenogram.pl)
+
+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,292 @@
+# Cenogram MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@cenogram/mcp-server)](https://www.npmjs.com/package/@cenogram/mcp-server)
+[![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**
+
+MCP server for Polish real estate data. Access 7M+ 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.
+
+Data source: Polish national RCN registry (Rejestr Cen Nieruchomosci) | Platform: [cenogram.pl](https://cenogram.pl)
+
+## Get your API key
+
+1. Go to [cenogram.pl/api](https://cenogram.pl/api)
+2. Enter your email
+3. You'll receive your `cngrm_...` API key by email
+
+Manage your keys at [cenogram.pl/ustawienia](https://cenogram.pl/ustawienia).
+
+## Installation
+
+Pick your client. All options below use the hosted server — no local install needed (except npx/stdio).
+
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+One command — zero config files:
+
+```bash
+claude mcp add cenogram https://mcp.cenogram.pl/mcp \
+  -t http -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "cenogram": {
+      "type": "http",
+      "url": "https://mcp.cenogram.pl/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to your config file:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**HTTP remote** (Claude Desktop 0.9+):
+```json
+{
+  "mcpServers": {
+    "cenogram": {
+      "type": "http",
+      "url": "https://mcp.cenogram.pl/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+**Stdio fallback** (older versions — requires Node.js >= 18):
+```json
+{
+  "mcpServers": {
+    "cenogram": {
+      "command": "npx",
+      "args": ["-y", "@cenogram/mcp-server@latest"],
+      "env": {
+        "CENOGRAM_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code / GitHub Copilot</strong></summary>
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "cenogram": {
+      "type": "http",
+      "url": "https://mcp.cenogram.pl/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+**HTTP remote:**
+```json
+{
+  "mcpServers": {
+    "cenogram": {
+      "type": "http",
+      "url": "https://mcp.cenogram.pl/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+If HTTP doesn't work, use the **npx (stdio)** option below instead.
+
+</details>
+
+<details>
+<summary><strong>Cline</strong></summary>
+
+In VS Code: Settings > Cline > MCP Servers. Add:
+
+```json
+{
+  "cenogram": {
+    "type": "http",
+    "url": "https://mcp.cenogram.pl/mcp",
+    "headers": {
+      "Authorization": "Bearer YOUR_API_KEY"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>npx (stdio) — local/offline</strong></summary>
+
+Requires **Node.js >= 18**. Use this if you want to run the server locally instead of connecting to the hosted one.
+
+```json
+{
+  "mcpServers": {
+    "cenogram": {
+      "command": "npx",
+      "args": ["-y", "@cenogram/mcp-server@latest"],
+      "env": {
+        "CENOGRAM_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+| Client | Config file |
+|---|---|
+| Cursor | `.cursor/mcp.json` |
+| Claude Code | `.mcp.json` in your project |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline | VS Code settings > Cline > MCP Servers |
+
+</details>
+
+## Configuration
+
+| Env Variable | Required | Default | Description |
+|---|---|---|---|
+| `CENOGRAM_API_KEY` | **Yes** (stdio) | — | API key from [cenogram.pl/api](https://cenogram.pl/api) |
+| `CENOGRAM_API_URL` | No | `https://cenogram.pl` | API base URL |
+| `MCP_TRANSPORT` | No | `stdio` | Set to `http` for Streamable HTTP mode |
+| `MCP_PORT` | No | `3002` | HTTP server port (HTTP mode only) |
+| `CENOGRAM_CLIENT_ID` | No | auto-generated | Persistent client identifier |
+
+You can also use the `--http` CLI flag instead of `MCP_TRANSPORT=http`.
+
+## Example Prompts
+
+**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 gruntow w promieniu 5km od centrum Wroclawia powyzej 500 000 PLN"
+- "Porownaj ceny mieszkan na Mokotowie i Woli"
+- "Pokaz rozklad cen nieruchomosci w Polsce"
+
+**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 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"
+
+## Tools
+
+| Tool | Description | Key Parameters |
+|---|---|---|
+| `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 |
+| `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 |
+| `compare_locations` | Compare stats across 2-5 districts | districts (comma-separated), propertyType |
+
+### Location naming
+
+- Most cities: use the city name directly (e.g., "Gdansk", "Lublin")
+- Warsaw: use district names ("Mokotow", "Srodmiescie", "Wola") -- "Warszawa" won't match
+- Krakow: use sub-districts ("Krakow-Podgorze", "Krakow-Srodmiescie") — plain "Krakow" won't match
+- Use `list_locations` to find valid names
+
+### Property types
+
+| Value | Polish | English |
+|---|---|---|
+| `land` | Grunt | Land plot |
+| `building` | Budynek | Building |
+| `developed_land` | Grunt zabudowany | Developed land |
+| `unit` | Lokal | Apartment/unit |
+
+### Workflows
+
+Results include parcel IDs and GPS coordinates, enabling multi-step research:
+
+```
+1. Search by address    -> search_transactions(location="Mokotow", street="Pulawska", buildingNumber="15")
+2. Note parcel_id and coordinates from results
+3. Search nearby        -> search_by_area(lat=52.19, lng=21.01, radiusKm=2, propertyType="unit")
+4. Compare prices       -> get_price_statistics(location="Mokotow")
+```
+
+This mimics how a property appraiser finds comparable transactions for valuation reports.
+
+## Data
+
+- **7M+ transactions** from all of Poland (380+ counties)
+- **Date range:** 2003 - present
+- **Source:** Polish national RCN registry (Rejestr Cen Nieruchomosci)
+- **Refresh:** periodic updates from RCN
+
+## Troubleshooting
+
+**"Error: CENOGRAM_API_KEY is required"** — This only applies to stdio mode. Make sure `CENOGRAM_API_KEY` is set in the `env` block of your MCP config. For HTTP remote, the key goes in the `Authorization` header instead.
+
+**npx hangs or fails** — Check your Node.js version with `node -v`. The stdio mode requires Node.js >= 18. If you're on an older version, use the HTTP remote option instead (no Node.js needed).
+
+**"Warszawa" returns 0 results** — Warsaw uses district names (Mokotow, Wola, Srodmiescie, Bemowo, etc.). Use `list_locations(search="warsz")` to find valid names. Same applies to Krakow (use "Krakow-Podgorze", "Krakow-Srodmiescie", etc.).
+
+**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.
+
+## Development
+
+```bash
+git clone https://github.com/cenogram/mcp-server.git
+cd mcp-server
+npm install
+npm test
+npm run build
+```
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,203 @@
+export interface StatsResponse {
+    counts: {
+        transactions: number;
+        parcels: number;
+        buildings: number;
+        units: number;
+        addresses: number;
+    };
+    prices: {
+        total: number;
+        avg_price: number;
+        median_price: number;
+        min_price: number;
+        max_price: number;
+    };
+    dateRange: {
+        min_date: string;
+        max_date: string;
+    };
+    byDistrict: {
+        district: string;
+        transaction_count: number;
+    }[];
+    byPropertyType: {
+        type: number;
+        total: number;
+        label: string;
+    }[];
+    byMarketType: {
+        type: number;
+        total: number;
+        label: string;
+    }[];
+}
+export interface Transaction {
+    id: string;
+    transaction_date: string;
+    property_type: number;
+    market_type: number;
+    price_gross: number;
+    usable_area_m2: number | null;
+    price_per_m2: number | null;
+    rooms: number | null;
+    floor: number | null;
+    district: string | null;
+    street: string | null;
+    building_number: string | null;
+    city: string | null;
+    parcel_area: number | null;
+    unit_function: number | null;
+    parcel_id: string | null;
+    county_name: string | null;
+    voivodeship_name: string | null;
+    centroid: {
+        type: string;
+        coordinates: [number, number];
+    } | null;
+}
+export interface TransactionsResponse {
+    data: Transaction[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        pages: number;
+        estimated?: boolean;
+    };
+}
+export interface TransactionsSummary {
+    median_price_m2: number | null;
+    avg_area: number | null;
+    min_date: string | null;
+    max_date: string | null;
+    total: number;
+}
+export interface PricePerM2Row {
+    district: string;
+    avg_price_m2: number;
+    median_price_m2: number;
+    count: number;
+}
+export interface HistogramBin {
+    bucket: number;
+    count: number;
+    range_min: number;
+    range_max: number;
+}
+export interface CreditInfo {
+    balance: number;
+    cost: number;
+}
+export interface ApiResponse<T> {
+    data: T;
+    creditInfo: CreditInfo | null;
+}
+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>>;
+export interface TransactionParams {
+    district?: string;
+    street?: string;
+    buildingNumber?: string;
+    parcelId?: string;
+    propertyType?: number;
+    marketType?: number;
+    minPrice?: number;
+    maxPrice?: number;
+    dateFrom?: string;
+    dateTo?: string;
+    minArea?: number;
+    maxArea?: number;
+    bbox?: string;
+    limit?: number;
+    page?: number;
+    sort?: string;
+    order?: string;
+}
+export declare function getTransactions(p: TransactionParams, apiKey?: string): Promise<ApiResponse<TransactionsResponse>>;
+export declare function getTransactionsSummary(p: TransactionParams, apiKey?: string): Promise<ApiResponse<TransactionsSummary>>;
+export declare function getPricePerM2(apiKey?: string): Promise<ApiResponse<PricePerM2Row[]>>;
+export declare function getDistricts(apiKey?: string): Promise<ApiResponse<string[]>>;
+export declare function getPriceHistogram(bins?: number, max?: number, apiKey?: string): Promise<ApiResponse<HistogramBin[]>>;
+export interface ParcelSearchResult {
+    parcel_id: string;
+    district: string | null;
+    area_m2: number | null;
+    lat: number;
+    lng: number;
+}
+export interface ParcelSearchResponse {
+    results: ParcelSearchResult[];
+}
+export declare function searchParcels(q: string, limit?: number, apiKey?: string): Promise<ApiResponse<ParcelSearchResponse>>;
+export interface SpatialSearchParams {
+    polygon: {
+        type: "Polygon";
+        coordinates: number[][][];
+    };
+    propertyType?: number;
+    marketType?: number;
+    minPrice?: number;
+    maxPrice?: number;
+    dateFrom?: string;
+    dateTo?: string;
+    minArea?: number;
+    maxArea?: number;
+    district?: string;
+    street?: string;
+    limit?: number;
+}
+export interface SpatialFeatureProperties {
+    id: string;
+    price_gross: number;
+    transaction_date: string;
+    property_type: number;
+    market_type: number;
+    usable_area_m2: number | null;
+    price_per_m2: number | null;
+    rooms: number | null;
+    floor: number | null;
+    street: string | null;
+    building_number: string | null;
+    city: string | null;
+    district: string | null;
+    parcel_area: number | null;
+}
+export interface SpatialFeature {
+    type: "Feature";
+    geometry: {
+        type: string;
+        coordinates: [number, number];
+    } | null;
+    properties: SpatialFeatureProperties;
+}
+export interface SpatialSearchResponse {
+    type: "FeatureCollection";
+    features: SpatialFeature[];
+    truncated: boolean;
+    total: number;
+}
+export declare function searchByPolygon(p: SpatialSearchParams, apiKey?: string): Promise<ApiResponse<SpatialSearchResponse>>;
+export interface CompareEntry {
+    median_price_m2: number | null;
+    avg_area: number | null;
+    min_date: string | null;
+    max_date: string | null;
+    total: number;
+    suggestions?: string[];
+}
+export type CompareResponse = Record<string, CompareEntry>;
+export interface CompareParams {
+    districts: string;
+    propertyType?: number;
+    marketType?: number;
+    minPrice?: number;
+    maxPrice?: number;
+    dateFrom?: string;
+    dateTo?: string;
+    minArea?: number;
+    maxArea?: number;
+    street?: string;
+}
+export declare function compareLocations(p: CompareParams, apiKey?: string): Promise<ApiResponse<CompareResponse>>;

package/dist/api-client.js

@@ -0,0 +1,177 @@
+import { getClientId } from "./client-id.js";
+const BASE_URL = process.env.CENOGRAM_API_URL || "https://cenogram.pl";
+function extractCreditInfo(res) {
+    if (!res.headers)
+        return null;
+    const balance = parseInt(res.headers.get("X-Credits-Balance") ?? "", 10);
+    const cost = parseInt(res.headers.get("X-Credits-Cost") ?? "", 10);
+    if (isNaN(balance) || isNaN(cost))
+        return null;
+    return { balance, cost };
+}
+// ── Shared HTTP helpers ────────────────────────────────────────────
+function buildHeaders(apiKey) {
+    const headers = {
+        "X-Source": "mcp-server",
+        "X-Cenogram-Client-Id": getClientId(),
+    };
+    const key = apiKey ?? process.env.CENOGRAM_API_KEY;
+    if (key)
+        headers["Authorization"] = `Bearer ${key}`;
+    return headers;
+}
+async function handleErrorResponse(res) {
+    if (res.status === 402) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(`Niewystarczające tokeny API. Saldo: ${body.currentBalance ?? 0}, wymagane: ${body.creditsRequired ?? "?"}. Doładuj: https://cenogram.pl/api#cennik`);
+    }
+    if (res.status === 429) {
+        const retryAfter = res.headers?.get?.("Retry-After");
+        const days = retryAfter ? Math.ceil(parseInt(retryAfter, 10) / 86400) : null;
+        const resetInfo = days !== null ? ` Reset za ${days} ${days === 1 ? "dzień" : "dni"}.` : "";
+        throw new Error(`Zbyt wiele zapytań.${resetInfo}`);
+    }
+    throw new Error(`API error: HTTP ${res.status}`);
+}
+function toQueryParams(obj) {
+    const params = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v != null && v !== "")
+            params[k] = String(v);
+    }
+    return params;
+}
+// ── HTTP client ─────────────────────────────────────────────────────
+export async function fetchApi(path, params, apiKey) {
+    const url = new URL(path, BASE_URL);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== "")
+                url.searchParams.set(k, v);
+        }
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10_000);
+    try {
+        const res = await fetch(url.toString(), { signal: controller.signal, headers: buildHeaders(apiKey) });
+        if (!res.ok)
+            await handleErrorResponse(res);
+        return { data: (await res.json()), creditInfo: extractCreditInfo(res) };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function fetchApiPost(path, body, apiKey) {
+    const url = new URL(path, BASE_URL);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const headers = buildHeaders(apiKey);
+        headers["Content-Type"] = "application/json";
+        const res = await fetch(url.toString(), {
+            method: "POST",
+            signal: controller.signal,
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            await handleErrorResponse(res);
+        return { data: (await res.json()), creditInfo: extractCreditInfo(res) };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// ── Typed wrappers ──────────────────────────────────────────────────
+export function getStats(apiKey) {
+    return fetchApi("/api/stats", undefined, apiKey);
+}
+export function getTransactions(p, apiKey) {
+    return fetchApi("/api/transactions", toQueryParams({
+        district: p.district,
+        street: p.street,
+        buildingNumber: p.buildingNumber,
+        parcelId: p.parcelId,
+        propertyType: p.propertyType,
+        marketType: p.marketType,
+        minPrice: p.minPrice,
+        maxPrice: p.maxPrice,
+        dateFrom: p.dateFrom,
+        dateTo: p.dateTo,
+        minArea: p.minArea,
+        maxArea: p.maxArea,
+        bbox: p.bbox,
+        limit: p.limit,
+        page: p.page,
+        sort: p.sort,
+        order: p.order,
+    }), apiKey);
+}
+export function getTransactionsSummary(p, apiKey) {
+    return fetchApi("/api/transactions/summary", toQueryParams({
+        district: p.district,
+        street: p.street,
+        propertyType: p.propertyType,
+        marketType: p.marketType,
+        minPrice: p.minPrice,
+        maxPrice: p.maxPrice,
+        dateFrom: p.dateFrom,
+        dateTo: p.dateTo,
+        minArea: p.minArea,
+        maxArea: p.maxArea,
+        bbox: p.bbox,
+    }), apiKey);
+}
+export function getPricePerM2(apiKey) {
+    return fetchApi("/api/price-per-m2", undefined, apiKey);
+}
+export function getDistricts(apiKey) {
+    return fetchApi("/api/districts", undefined, apiKey);
+}
+export function getPriceHistogram(bins = 20, max = 3_000_000, apiKey) {
+    return fetchApi("/api/stats/price-histogram", toQueryParams({ bins, max }), apiKey);
+}
+export function searchParcels(q, limit, apiKey) {
+    return fetchApi("/api/parcels/search", toQueryParams({ q, limit }), apiKey);
+}
+export function searchByPolygon(p, apiKey) {
+    const body = { polygon: p.polygon };
+    if (p.propertyType != null)
+        body.propertyType = p.propertyType;
+    if (p.marketType != null)
+        body.marketType = p.marketType;
+    if (p.minPrice != null)
+        body.minPrice = p.minPrice;
+    if (p.maxPrice != null)
+        body.maxPrice = p.maxPrice;
+    if (p.dateFrom)
+        body.dateFrom = p.dateFrom;
+    if (p.dateTo)
+        body.dateTo = p.dateTo;
+    if (p.minArea != null)
+        body.minArea = p.minArea;
+    if (p.maxArea != null)
+        body.maxArea = p.maxArea;
+    if (p.district)
+        body.district = p.district;
+    if (p.street)
+        body.street = p.street;
+    if (p.limit != null)
+        body.limit = p.limit;
+    return fetchApiPost("/api/transactions/spatial", body, apiKey);
+}
+export function compareLocations(p, apiKey) {
+    return fetchApi("/api/transactions/summary/compare", toQueryParams({
+        districts: p.districts,
+        propertyType: p.propertyType,
+        marketType: p.marketType,
+        minPrice: p.minPrice,
+        maxPrice: p.maxPrice,
+        dateFrom: p.dateFrom,
+        dateTo: p.dateTo,
+        minArea: p.minArea,
+        maxArea: p.maxArea,
+        street: p.street,
+    }), apiKey);
+}

package/dist/client-id.d.ts

@@ -0,0 +1 @@
+export declare function getClientId(): string;