@cenogram/mcp-server 0.1.6 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 **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.
+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.
 
 Data source: Polish national RCN registry (Rejestr Cen Nieruchomosci) | Platform: [cenogram.pl](https://cenogram.pl)
 
@@ -62,22 +62,7 @@ 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):
+**npx (stdio):**
 ```json
 {
   "mcpServers": {
@@ -262,7 +247,7 @@ This mimics how a property appraiser finds comparable transactions for valuation
 
 ## Data
 
-- **7M+ transactions** from all of Poland (380+ counties)
+- **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

package/dist/api-client.d.ts

@@ -94,11 +94,13 @@ export interface ApiResponse<T> {
     data: T;
     creditInfo: CreditInfo | null;
 }
+export declare function encodeOAuthCtx(userId: string, grantId: string): string;
 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;
+    teryt?: string;
     street?: string;
     buildingNumber?: string;
     parcelId?: string;
@@ -123,6 +125,13 @@ export declare function getTransactions(p: TransactionParams, apiKey?: string):
 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 interface LocationItem {
+    code: string;
+    name: string;
+    typeName: string | null;
+    level: "voivodeship" | "county" | "municipality" | "precinct";
+}
+export declare function getLocations(parent?: string, apiKey?: string): Promise<ApiResponse<LocationItem[]>>;
 export declare function getPriceHistogram(bins?: number, max?: number, apiKey?: string): Promise<ApiResponse<HistogramBin[]>>;
 export interface ParcelSearchResult {
     parcel_id: string;

package/dist/api-client.js

@@ -1,4 +1,7 @@
+import { fetch } from "undici";
 import { getClientId } from "./client-id.js";
+import { authErrorMessage, getAuthMode } from "./error-messages.js";
+import { requestContext } from "./request-context.js";
 const BASE_URL = process.env.CENOGRAM_API_URL || "https://cenogram.pl";
 function extractCreditInfo(res) {
     if (!res.headers)
@@ -9,29 +12,52 @@ function extractCreditInfo(res) {
         return null;
     return { balance, cost };
 }
+// ── OAuth internal auth ────────────────────────────────────────────
+// SOH char (\x01) is impossible in base64url or ctx_ keys - used as both prefix and separator
+const OAUTH_CTX_PREFIX = "\x01";
+export function encodeOAuthCtx(userId, grantId) {
+    // \x01{userId}\x01{grantId} - \x01 cannot appear in UUIDs (hex + hyphens only)
+    return `${OAUTH_CTX_PREFIX}${userId}${OAUTH_CTX_PREFIX}${grantId}`;
+}
 // ── Shared HTTP helpers ────────────────────────────────────────────
 function buildHeaders(apiKey) {
     const headers = {
         "X-Source": "mcp-server",
         "X-Cenogram-Client-Id": getClientId(),
     };
+    const ctx = requestContext.getStore();
+    if (ctx?.clientUserAgent)
+        headers["X-MCP-User-Agent"] = ctx.clientUserAgent;
     const key = apiKey ?? process.env.CENOGRAM_API_KEY;
-    if (key)
+    if (key?.startsWith(OAUTH_CTX_PREFIX)) {
+        const rest = key.slice(OAUTH_CTX_PREFIX.length);
+        const sepIdx = rest.indexOf(OAUTH_CTX_PREFIX);
+        if (sepIdx <= 0) {
+            throw new Error("BUG: malformed OAuth context key");
+        }
+        const internalSecret = process.env.INTERNAL_AUTH_SECRET;
+        if (internalSecret) {
+            headers["X-Internal-Auth"] = internalSecret;
+        }
+        headers["X-OAuth-User"] = rest.slice(0, sepIdx);
+        headers["X-OAuth-Grant"] = rest.slice(sepIdx + OAUTH_CTX_PREFIX.length);
+    }
+    else 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`);
-    }
+async function handleErrorResponse(res, apiKey) {
+    // 429 has special Retry-After handling - keep dedicated path
     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}`);
+        const resetInfo = days !== null ? ` Resets in ${days} day(s).` : "";
+        throw new Error(`Too many requests.${resetInfo}`);
     }
-    throw new Error(`API error: HTTP ${res.status}`);
+    const body = (await res.json().catch(() => ({})));
+    const mode = getAuthMode(apiKey ?? process.env.CENOGRAM_API_KEY);
+    throw new Error(authErrorMessage(res.status, mode, body));
 }
 function toQueryParams(obj) {
     const params = {};
@@ -55,7 +81,7 @@ export async function fetchApi(path, params, apiKey) {
     try {
         const res = await fetch(url.toString(), { signal: controller.signal, headers: buildHeaders(apiKey) });
         if (!res.ok)
-            await handleErrorResponse(res);
+            await handleErrorResponse(res, apiKey);
         return { data: (await res.json()), creditInfo: extractCreditInfo(res) };
     }
     finally {
@@ -76,7 +102,7 @@ export async function fetchApiPost(path, body, apiKey) {
             body: JSON.stringify(body),
         });
         if (!res.ok)
-            await handleErrorResponse(res);
+            await handleErrorResponse(res, apiKey);
         return { data: (await res.json()), creditInfo: extractCreditInfo(res) };
     }
     finally {
@@ -90,6 +116,7 @@ export function getStats(apiKey) {
 export function getTransactions(p, apiKey) {
     return fetchApi("/api/transactions", toQueryParams({
         district: p.district,
+        teryt: p.teryt,
         street: p.street,
         buildingNumber: p.buildingNumber,
         parcelId: p.parcelId,
@@ -114,6 +141,7 @@ export function getTransactions(p, apiKey) {
 export function getTransactionsSummary(p, apiKey) {
     return fetchApi("/api/transactions/summary", toQueryParams({
         district: p.district,
+        teryt: p.teryt,
         street: p.street,
         propertyType: p.propertyType,
         marketType: p.marketType,
@@ -135,6 +163,9 @@ export function getPricePerM2(apiKey) {
 export function getDistricts(apiKey) {
     return fetchApi("/api/districts", undefined, apiKey);
 }
+export function getLocations(parent, apiKey) {
+    return fetchApi("/api/locations", parent ? { parent } : undefined, apiKey);
+}
 export function getPriceHistogram(bins = 20, max = 3_000_000, apiKey) {
     return fetchApi("/api/stats/price-histogram", toQueryParams({ bins, max }), apiKey);
 }

package/dist/auth-dispatch.d.ts

@@ -0,0 +1,59 @@
+import { validateOAuthJwt, type ValidationReason } from "./oauth-jwt.js";
+export declare const RESOURCE_METADATA = "https://mcp.cenogram.pl/.well-known/oauth-protected-resource";
+export declare function sanitizeForLog(s: string): string;
+export type DispatchResult = {
+    kind: "passthrough";
+    apiKey: string;
+    log: {
+        evt: "auth.passthrough";
+        mode: "oauth";
+        grant_id: string;
+    } | {
+        evt: "auth.passthrough";
+        mode: "api_key";
+        key_prefix: string | null;
+    };
+} | {
+    kind: "401";
+    headers: {
+        "Content-Type": string;
+        "WWW-Authenticate": string;
+    };
+    body: {
+        error: string;
+        error_description: string;
+    };
+    log: {
+        evt: "auth.rejected";
+        reason: "missing" | "invalid_format" | "oversized_header" | ValidationReason;
+        kid: string | null;
+    };
+} | {
+    kind: "403";
+    headers: {
+        "Content-Type": string;
+        "WWW-Authenticate": string;
+    };
+    body: {
+        error: string;
+        error_description: string;
+    };
+    log: {
+        evt: "auth.rejected";
+        reason: "insufficient_scope";
+    };
+} | {
+    kind: "500";
+    headers: {
+        "Content-Type": string;
+    };
+    body: {
+        error: string;
+        error_description: string;
+    };
+    log: {
+        evt: "auth.config_missing";
+    };
+};
+export type ValidateJwtFn = typeof validateOAuthJwt;
+export declare function dispatchAuth(authHeader: string | undefined, validateJwt?: ValidateJwtFn): Promise<DispatchResult>;

package/dist/auth-dispatch.js

@@ -0,0 +1,168 @@
+import { validateOAuthJwt, OAuthConfigError } from "./oauth-jwt.js";
+import { encodeOAuthCtx } from "./api-client.js";
+export const RESOURCE_METADATA = "https://mcp.cenogram.pl/.well-known/oauth-protected-resource";
+// RFC 6750 § 3 quoted-string alphabet: %x20-21 / %x23-5B / %x5D-7E (ASCII visible without " or \)
+const QUOTED_RE = /^[\x20\x21\x23-\x5B\x5D-\x7E]*$/;
+// RFC 7235 BWS (bad whitespace): SP / HTAB
+const BEARER_RE = /^Bearer[ \t]+(.+)$/i;
+// JWT shape: 3 base64url segments separated by dots, starting with eyJ
+const JWT_SHAPE_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+// Log-unsafe codepoints (log poisoning via multi-byte UTF-8 controls):
+//   \x00-\x1F      ASCII C0 controls
+//   \x7F-\x9F      DEL + C1 controls (incl. U+0085 NEL = bytes 0xc2 0x85)
+//   U+2028, U+2029 Line/Paragraph Separator (NOT escaped by JSON.stringify)
+//   U+202A-U+202E  BiDi controls LRE/RLE/PDF/LRO/RLO (Trojan Source attacks)
+//   U+2066-U+2069  BiDi isolates LRI/RLI/FSI/PDI
+//   U+FEFF         Zero-Width No-Break Space / BOM
+// Goal: prevent log injection / terminal RTL render manipulation when user-controlled
+// bytes (kid in JWT header, suffix of cngrm_ API key) reach stderr JSON logs.
+// eslint-disable-next-line no-control-regex -- control chars in regex are the whole point
+const LOG_UNSAFE_RE = /[\x00-\x1F\x7F-\x9F\u2028\u2029\u202A-\u202E\u2066-\u2069\uFEFF]/g;
+export function sanitizeForLog(s) {
+    return s.replace(LOG_UNSAFE_RE, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+// Static descriptions for WWW-Authenticate header - quoted-safe ASCII, no user input echoed.
+// Note: unknown_key and invalid intentionally share the same description to avoid leaking
+// validation timing/identity info on the wire (security: minimize info oracle).
+const REASON_DESC = {
+    expired: "Token expired",
+    unknown_key: "Token validation failed",
+    invalid: "Token validation failed",
+};
+function quotedParam(name, value) {
+    if (!QUOTED_RE.test(value)) {
+        throw new Error(`BUG: WWW-Authenticate ${name} contains illegal chars: ${JSON.stringify(value)}`);
+    }
+    return `${name}="${value}"`;
+}
+function safeKid(h) {
+    return typeof h === "string" ? sanitizeForLog(h.slice(0, 64)) : null;
+}
+function build401(opts) {
+    const parts = ['Bearer realm="cenogram"'];
+    if (opts.errorParam)
+        parts.push(`error="${opts.errorParam}"`);
+    if (opts.description)
+        parts.push(quotedParam("error_description", opts.description));
+    parts.push(quotedParam("resource_metadata", RESOURCE_METADATA));
+    return {
+        headers: { "Content-Type": "application/json", "WWW-Authenticate": parts.join(", ") },
+        body: { error: opts.bodyError, error_description: opts.bodyDesc },
+    };
+}
+function build403(scope, description) {
+    const parts = [
+        'Bearer realm="cenogram"',
+        `error="insufficient_scope"`,
+        quotedParam("scope", scope),
+        quotedParam("error_description", description),
+        quotedParam("resource_metadata", RESOURCE_METADATA),
+    ];
+    return {
+        headers: { "Content-Type": "application/json", "WWW-Authenticate": parts.join(", ") },
+        body: { error: "insufficient_scope", error_description: description },
+    };
+}
+export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
+    // RFC 6750 §3.1: oversized auth attempt → invalid_token (client tried auth, not missing).
+    // 8192 B = below Node default http.maxHeaderSize (16KB), accommodates JWT with claims +
+    // Bearer prefix (~700-1500 bytes for current claim set: sub, scope, grant_id, client_id).
+    // Check before regex match to avoid ReDoS / memory on huge string.
+    const MAX_AUTH_HEADER_BYTES = 8192;
+    if (authHeader && Buffer.byteLength(authHeader, "utf-8") > MAX_AUTH_HEADER_BYTES) {
+        return {
+            kind: "401",
+            ...build401({
+                errorParam: "invalid_token",
+                description: "Authorization header too large",
+                bodyError: "invalid_token",
+                bodyDesc: "Authorization header exceeds maximum size",
+            }),
+            log: { evt: "auth.rejected", reason: "oversized_header", kid: null },
+        };
+    }
+    // Parse Bearer token (RFC 7235: BWS = SP/HTAB)
+    const match = authHeader?.match(BEARER_RE);
+    const rawToken = match?.[1]?.trim() ?? "";
+    if (!rawToken) {
+        return {
+            kind: "401",
+            ...build401({
+                bodyError: "missing_token",
+                bodyDesc: "Provide an OAuth access token or API key in Authorization: Bearer header.",
+            }),
+            log: { evt: "auth.rejected", reason: "missing", kid: null },
+        };
+    }
+    // Fast path: API key (most common). Format validation delegated to upstream API.
+    if (rawToken.startsWith("cngrm_")) {
+        return {
+            kind: "passthrough",
+            apiKey: rawToken,
+            log: { evt: "auth.passthrough", mode: "api_key", key_prefix: sanitizeForLog(rawToken.slice(0, 10)) },
+        };
+    }
+    // OAuth JWT shape check - reject anything that doesn't look like a JWT before crypto ops
+    if (!JWT_SHAPE_RE.test(rawToken)) {
+        return {
+            kind: "401",
+            ...build401({
+                errorParam: "invalid_token",
+                description: "Token format not recognized",
+                bodyError: "invalid_token",
+                bodyDesc: "Expected OAuth JWT or Cenogram API key (cngrm_...)",
+            }),
+            log: { evt: "auth.rejected", reason: "invalid_format", kid: null },
+        };
+    }
+    // Validate JWT
+    let result;
+    try {
+        result = await validateJwt(rawToken);
+    }
+    catch (e) {
+        if (e instanceof OAuthConfigError) {
+            return {
+                kind: "500",
+                headers: { "Content-Type": "application/json" },
+                body: { error: "server_misconfigured", error_description: "OAuth not configured on server" },
+                log: { evt: "auth.config_missing" },
+            };
+        }
+        throw e;
+    }
+    if (!result.ok) {
+        // Extract kid from header for logging (best-effort, not on wire)
+        let headerKid = null;
+        try {
+            const headerJson = JSON.parse(Buffer.from(rawToken.split(".")[0], "base64url").toString("utf-8"));
+            headerKid = safeKid(headerJson.kid);
+        }
+        catch {
+            // ignore - kid logging is best-effort
+        }
+        return {
+            kind: "401",
+            ...build401({
+                errorParam: "invalid_token",
+                description: REASON_DESC[result.reason],
+                bodyError: "invalid_token",
+                bodyDesc: REASON_DESC[result.reason],
+            }),
+            log: { evt: "auth.rejected", reason: result.reason, kid: headerKid },
+        };
+    }
+    if (!result.claims.scope.split(" ").includes("mcp")) {
+        return {
+            kind: "403",
+            ...build403("mcp", "Token does not include 'mcp' scope"),
+            log: { evt: "auth.rejected", reason: "insufficient_scope" },
+        };
+    }
+    return {
+        kind: "passthrough",
+        apiKey: encodeOAuthCtx(result.claims.sub, result.claims.grant_id),
+        // Sanitize grant_id for log consistency with key_prefix/kid (defense in depth - JWT is signed but spec allows custom claims).
+        log: { evt: "auth.passthrough", mode: "oauth", grant_id: sanitizeForLog(result.claims.grant_id) },
+    };
+}

package/dist/error-messages.d.ts

@@ -0,0 +1,8 @@
+export type AuthMode = "oauth" | "api_key" | "stdio_env" | "none";
+export declare function getAuthMode(apiKey?: string): AuthMode;
+export interface ErrorBody {
+    error?: string;
+    currentBalance?: number;
+    creditsRequired?: number;
+}
+export declare function authErrorMessage(status: number, mode: AuthMode, body?: ErrorBody): string;

package/dist/error-messages.js

@@ -0,0 +1,37 @@
+// SOH char (\x01) - must match OAUTH_CTX_PREFIX in api-client.ts
+const OAUTH_CTX_PREFIX = "\x01";
+export function getAuthMode(apiKey) {
+    if (!apiKey)
+        return "none";
+    if (apiKey.startsWith(OAUTH_CTX_PREFIX))
+        return "oauth";
+    if (apiKey.startsWith("cngrm_"))
+        return "api_key";
+    return "stdio_env";
+}
+export function authErrorMessage(status, mode, body = {}) {
+    switch (status) {
+        case 401:
+            if (mode === "oauth") {
+                return "Connection to Cenogram expired or was revoked. In Claude open: Settings > Connectors > Cenogram, disconnect and reconnect.";
+            }
+            return "API key rejected. Check https://cenogram.pl/api/keys if it's still active.";
+        case 402: {
+            const balance = body.currentBalance ?? 0;
+            const required = body.creditsRequired ?? "?";
+            if (mode === "oauth") {
+                return `Insufficient credits (balance: ${balance}, query cost: ${required}). Top up: https://cenogram.pl/api#cennik`;
+            }
+            return `Insufficient credits for key's account (balance: ${balance}, query cost: ${required}). Top up: https://cenogram.pl/api#cennik`;
+        }
+        case 403:
+            if (body.error === "email_not_verified") {
+                return "Account email not verified. Check your inbox, click the activation link, then retry.";
+            }
+            return `Access denied (HTTP 403).`;
+        case 503:
+            return "Cenogram temporarily unavailable (maintenance mode). Try again shortly.";
+        default:
+            return `Cenogram API unavailable (HTTP ${status}). Try again shortly.`;
+    }
+}

package/dist/formatters.d.ts

@@ -1,4 +1,4 @@
-import type { Transaction, TransactionsResponse, TransactionsSummary, StatsResponse, PricePerM2Row, HistogramBin, ParcelSearchResponse, SpatialSearchResponse, CompareResponse } from "./api-client.js";
+import type { Transaction, TransactionsResponse, TransactionsSummary, StatsResponse, PricePerM2Row, HistogramBin, ParcelSearchResponse, SpatialSearchResponse, CompareResponse, LocationItem } from "./api-client.js";
 export declare function formatPLN(value: number | null | undefined): string;
 export declare function formatArea(m2: number | null | undefined): string;
 export declare function formatNumber(value: number | null | undefined): string;
@@ -9,4 +9,5 @@ export declare function formatPriceStats(rows: PricePerM2Row[], location?: strin
 export declare function formatHistogram(bins: HistogramBin[]): string;
 export declare function formatParcelResults(res: ParcelSearchResponse, query: string): string;
 export declare function formatSpatialResults(res: SpatialSearchResponse): string;
+export declare function formatLocationHierarchy(items: LocationItem[], parent?: string): string;
 export declare function formatCompareResults(res: CompareResponse): string;

package/dist/formatters.js

@@ -24,10 +24,12 @@ export function formatNumber(value) {
 function formatTransactionCore(f) {
     const parts = [];
     // Address with optional county/voivodeship
-    const addr = [f.street, f.building_number].filter(Boolean).join(" ");
+    const streetAddr = [f.street, f.building_number].filter(Boolean).join(" ");
     const district = f.district || f.city;
-    const region = [f.county_name ? `pow. ${f.county_name}` : null, f.voivodeship_name ? `woj. ${f.voivodeship_name}` : null].filter(Boolean).join(", ");
-    const loc = [addr, district].filter(Boolean).join(", ");
+    const region = [f.county_name ? `county: ${f.county_name}` : null, f.voivodeship_name ? `voivodeship: ${f.voivodeship_name}` : null].filter(Boolean).join(", ");
+    const loc = f.street
+        ? [streetAddr, district].filter(Boolean).join(", ")
+        : [district, f.building_number].filter(Boolean).join(" ");
     if (loc && region)
         parts.push(`${loc} (${region})`);
     else if (loc)
@@ -172,8 +174,9 @@ export function formatParcelResults(res, query) {
     for (const [i, p] of res.results.entries()) {
         const district = p.district ?? "Unknown";
         const area = p.area_m2 != null ? formatArea(p.area_m2) : "N/A";
+        const location = `${p.lat.toFixed(4)}\u00B0N, ${p.lng.toFixed(4)}\u00B0E`;
         lines.push(`${i + 1}. ${p.parcel_id}`);
-        lines.push(`   District: ${district} | Area: ${area} | Location: ${p.lat.toFixed(4)}\u00B0N, ${p.lng.toFixed(4)}\u00B0E`);
+        lines.push(`   District: ${district} | Area: ${area} | Location: ${location}`);
     }
     return lines.join("\n");
 }
@@ -206,6 +209,39 @@ export function formatSpatialResults(res) {
     }
     return lines.join("\n");
 }
+// ── Location hierarchy formatting ─────────────────────────────────
+const LEVEL_TIPS = {
+    voivodeship: "Use a 2-digit code as 'parent' to browse counties.",
+    county: "Use a 4-digit code as 'parent' to browse municipalities.",
+    municipality: "Use a 6-digit code as 'parent' to browse precincts, or use any code with 'teryt' in search_transactions.",
+    precinct: "Use these precinct codes with 'teryt' in search_transactions for precise area filtering.",
+};
+export function formatLocationHierarchy(items, parent) {
+    if (items.length === 0) {
+        if (parent) {
+            if (parent.length >= 6) {
+                return `No sub-locations found for TERYT code '${parent}'. This may be a leaf code - use it directly with search_transactions(teryt='${parent}').`;
+            }
+            return `No sub-locations found for TERYT code '${parent}'. Verify the code is correct using list_locations.`;
+        }
+        return "No locations available.";
+    }
+    const level = items[0].level;
+    const header = parent
+        ? `TERYT location hierarchy (parent: ${parent}, level: ${level}):`
+        : `TERYT location hierarchy (Poland, level: ${level}):`;
+    const plural = { voivodeship: "voivodeships", county: "counties", municipality: "municipalities", precinct: "precincts" };
+    const lines = [header, "", `Found ${items.length} ${plural[level] ?? `${level}s`}:`, ""];
+    for (const item of items) {
+        const typeSuffix = item.typeName ? ` (${item.typeName})` : "";
+        lines.push(`  ${item.code} - ${item.name}${typeSuffix}`);
+    }
+    const tip = LEVEL_TIPS[level];
+    if (tip) {
+        lines.push("", `Tip: ${tip}`);
+    }
+    return lines.join("\n");
+}
 // ── Compare locations formatting ───────────────────────────────────
 export function formatCompareResults(res) {
     const districts = Object.keys(res);

package/dist/index.js

@@ -4,7 +4,19 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { readFileSync, realpathSync } from "node:fs";
+import { fetch } from "undici";
 import { registerTools } from "./tools.js";
+import { dispatchAuth, sanitizeForLog } from "./auth-dispatch.js";
+import { requestContext } from "./request-context.js";
+function logAuth(payload, level) {
+    process.stderr.write(JSON.stringify({ level, ...payload }) + "\n");
+}
+// ── Node version check ─────────────────────────────────────────────
+const [nodeMajor] = process.versions.node.split(".").map(Number);
+if (nodeMajor != null && nodeMajor < 18) {
+    process.stderr.write(`Warning: @cenogram/mcp-server recommends Node.js >= 18 (current: ${process.version}). ` +
+        "The server will try to run, but some features may not work.\n");
+}
 // ── Version ────────────────────────────────────────────────────────
 const __dirname = dirname(fileURLToPath(import.meta.url));
 let PKG_VERSION = "0.1.0";
@@ -16,13 +28,16 @@ catch { /* fallback to hardcoded if dist/ used standalone */ }
 export function createMcpServer(apiKey) {
     const server = new McpServer({ name: "cenogram-mcp-server", version: PKG_VERSION }, {
         instructions: [
-            "Cenogram MCP Server - 7M+ verified real estate transactions from Poland's official RCN registry (Rejestr Cen Nieruchomości). Transaction prices from notarial deeds - NOT asking/listing prices. Data from 2003 to present, ~380 counties, refreshed every ~2 weeks.",
+            "Cenogram MCP Server - 8M+ verified real estate transactions from Poland's official RCN registry (Rejestr Cen Nieruchomości). Transaction prices from notarial deeds - NOT asking/listing prices. Data from 2003 to present, 380 counties, refreshed every ~2 weeks.",
             "",
             "CRITICAL - District names (ALWAYS verify first):",
             "- NEVER guess district names. Call list_locations(search=\"city\") first.",
             "- 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",
+            "- Most cities (Gdańsk, Gdynia, Sopot, Poznań, Wrocław): just the city name, no sub-districts",
+            "- Neighborhoods/osiedla (Nowy Dwór, Oliwa, Jeżyce) are NOT TERYT districts. Start with search_by_area (radiusKm 0.5-1.0), then refine with search_by_polygon if needed.",
+            "- TERYT hierarchy: For precise administrative filtering (avoids name ambiguity), use list_locations(parent) to browse TERYT codes, then search_transactions(teryt=code).",
+            "- Use 'location' for quick city searches, 'teryt' when you need exact administrative boundaries.",
             "",
             "Workflows:",
             "- Market analysis: get_market_overview → get_price_statistics(location) → search_transactions",
@@ -31,6 +46,7 @@ export function createMcpServer(apiKey) {
             "- Address search: search_transactions(location, street, buildingNumber)",
             "- Radius search: search_by_area(lat, lng, radiusKm) - for geographic proximity",
             "- Polygon search: search_by_polygon - coordinates are [longitude, latitude], first=last point, max 500 vertices",
+            "- TERYT drill-down: list_locations() → list_locations(parent=voivodeshipCode) → list_locations(parent=countyCode) → search_transactions(teryt=municipalityCode)",
             "",
             "Data notes:",
             "- price_per_m2 only meaningful for apartments (propertyType=\"unit\")",
@@ -48,27 +64,102 @@ async function main() {
     if (mode === "http") {
         const { createServer } = await import("node:http");
         const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
+        if (process.env.NODE_ENV === "production") {
+            if (!process.env.OAUTH_JWT_KID)
+                throw new Error("OAUTH_JWT_KID required in production");
+            if (!process.env.OAUTH_JWT_PUBLIC_KEY)
+                throw new Error("OAUTH_JWT_PUBLIC_KEY required in production");
+            if (!process.env.INTERNAL_AUTH_SECRET)
+                throw new Error("INTERNAL_AUTH_SECRET required in production");
+        }
         const port = parseInt(process.env.MCP_PORT || "3002", 10);
         const handleHttpRequest = async (req, res) => {
             try {
                 const pathname = req.url?.split("?")[0];
                 if (pathname === "/mcp") {
-                    const auth = req.headers.authorization;
-                    const apiKeyFromHeader = auth?.startsWith("Bearer ") ? auth.slice(7).trim() : undefined;
-                    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-                    const mcpServer = createMcpServer(apiKeyFromHeader);
-                    try {
-                        await mcpServer.connect(transport);
-                        await transport.handleRequest(req, res);
+                    const dispatch = await dispatchAuth(req.headers.authorization);
+                    if (dispatch.kind === "passthrough") {
+                        logAuth(dispatch.log, "info");
                     }
-                    finally {
-                        await transport.close();
-                        await mcpServer.close();
+                    else if (dispatch.kind === "500") {
+                        logAuth(dispatch.log, "error");
+                        res.writeHead(500, dispatch.headers).end(JSON.stringify(dispatch.body));
+                        return;
+                    }
+                    else {
+                        const level = dispatch.kind === "401" && dispatch.log.reason === "missing" ? "info" : "warn";
+                        const clientIp = (req.headers["cf-connecting-ip"] ?? req.headers["x-forwarded-for"] ?? req.socket.remoteAddress ?? "");
+                        logAuth({
+                            ...dispatch.log,
+                            method: req.method,
+                            ua: sanitizeForLog((req.headers["user-agent"] ?? "").slice(0, 128)),
+                            ip: sanitizeForLog(clientIp.split(",")[0].trim().slice(0, 45)),
+                        }, level);
+                        const status = dispatch.kind === "401" ? 401 : 403;
+                        res.writeHead(status, dispatch.headers).end(JSON.stringify(dispatch.body));
+                        return;
                     }
+                    const clientUA = (req.headers["user-agent"] ?? "").slice(0, 512) || undefined;
+                    await requestContext.run({ clientUserAgent: clientUA }, async () => {
+                        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+                        const mcpServer = createMcpServer(dispatch.apiKey);
+                        try {
+                            await mcpServer.connect(transport);
+                            await transport.handleRequest(req, res);
+                        }
+                        finally {
+                            await transport.close();
+                            await mcpServer.close();
+                        }
+                    });
+                }
+                else if (pathname === "/.well-known/oauth-protected-resource") {
+                    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "public, max-age=3600" }).end(JSON.stringify({
+                        resource: "https://mcp.cenogram.pl",
+                        authorization_servers: ["https://api.cenogram.pl"],
+                        scopes_supported: ["mcp"],
+                        bearer_methods_supported: ["header"],
+                    }));
+                }
+                else if (pathname === "/.well-known/mcp.json") {
+                    res.writeHead(200, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*", "Cache-Control": "public, max-age=3600" }).end(JSON.stringify({
+                        name: "Cenogram",
+                        description: "8M+ verified real estate transactions from Poland's official RCN registry. Transaction prices from notarial deeds, 380 counties, data from 2003.",
+                        icon: "https://cenogram.pl/apple-touch-icon.png",
+                        endpoint: "https://mcp.cenogram.pl/mcp",
+                    }));
                 }
                 else if (pathname === "/health") {
                     res.writeHead(200, { "Content-Type": "text/plain" }).end("ok");
                 }
+                else if (pathname === "/health/deep") {
+                    const apiUrl = process.env.CENOGRAM_API_URL || "https://cenogram.pl";
+                    const controller = new AbortController();
+                    const timeout = setTimeout(() => controller.abort(), 3_000);
+                    let apiStatus = "fail";
+                    let apiError;
+                    try {
+                        const apiRes = await fetch(`${apiUrl}/api/health`, { signal: controller.signal });
+                        if (apiRes.ok) {
+                            apiStatus = "ok";
+                        }
+                        else {
+                            apiError = `HTTP ${apiRes.status}`;
+                        }
+                    }
+                    catch (err) {
+                        apiError = err instanceof Error ? err.message : String(err);
+                    }
+                    finally {
+                        clearTimeout(timeout);
+                    }
+                    const code = apiStatus === "ok" ? 200 : 503;
+                    res.writeHead(code, { "Content-Type": "application/json" }).end(JSON.stringify({
+                        status: apiStatus === "ok" ? "ok" : "degraded",
+                        dependencies: { api: apiStatus, ...(apiError ? { apiError } : {}) },
+                        apiUrl,
+                    }));
+                }
                 else if (pathname === "/robots.txt") {
                     res.writeHead(200, { "Content-Type": "text/plain", "Cache-Control": "public, max-age=86400" }).end("User-agent: *\nDisallow: /\n");
                 }

package/dist/mappings.d.ts

@@ -8,7 +8,7 @@ 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) */
+/** Filter districts by location name (case-insensitive, diacritics-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. */

package/dist/mappings.js

@@ -94,14 +94,15 @@ export function radiusKmToBbox(lat, lng, radiusKm) {
     ];
 }
 // ── Location filtering ──────────────────────────────────────────────
-/** Filter districts by location name (case-insensitive includes match) */
+function stripDiacritics(s) {
+    return s.normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[łŁ]/g, (c) => c === "ł" ? "l" : "L");
+}
+/** Filter districts by location name (case-insensitive, diacritics-insensitive includes match) */
 export function filterByLocation(location, districts) {
-    const lower = location.toLowerCase();
-    return districts.filter((d) => d.toLowerCase().includes(lower));
+    const needle = stripDiacritics(location.toLowerCase());
+    return districts.filter((d) => stripDiacritics(d.toLowerCase()).includes(needle));
 }
 // ── 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",

package/dist/oauth-jwt.d.ts

@@ -0,0 +1,19 @@
+export declare const MCP_AUDIENCE = "https://mcp.cenogram.pl";
+export interface OAuthJwtClaims {
+    sub: string;
+    scope: string;
+    grant_id: string;
+    client_id: string;
+}
+export type ValidationReason = "expired" | "unknown_key" | "invalid";
+export type ValidationResult = {
+    ok: true;
+    claims: OAuthJwtClaims;
+} | {
+    ok: false;
+    reason: ValidationReason;
+};
+export declare class OAuthConfigError extends Error {
+    constructor(message?: string);
+}
+export declare function validateOAuthJwt(token: string): Promise<ValidationResult>;

package/dist/oauth-jwt.js

@@ -0,0 +1,65 @@
+import { decodeProtectedHeader, importSPKI, jwtVerify, errors as joseErrors } from "jose";
+export const MCP_AUDIENCE = "https://mcp.cenogram.pl";
+const ISSUER = "https://api.cenogram.pl";
+export class OAuthConfigError extends Error {
+    constructor(message = "OAuth not configured: OAUTH_JWT_KID and OAUTH_JWT_PUBLIC_KEY required") {
+        super(message);
+        this.name = "OAuthConfigError";
+    }
+}
+let cachedKey = null;
+let cachedKid;
+async function getKeyPair() {
+    const kid = process.env.OAUTH_JWT_KID;
+    const pem = (process.env.OAUTH_JWT_PUBLIC_KEY ?? "").replace(/\\\\n|\\n/g, "\n");
+    if (!kid || !pem)
+        throw new OAuthConfigError();
+    if (cachedKey && cachedKid === kid)
+        return { key: cachedKey, kid };
+    cachedKey = await importSPKI(pem, "RS256");
+    cachedKid = kid;
+    return { key: cachedKey, kid };
+}
+// kid check BEFORE signature verify - rejects unknown kid without expensive crypto op
+export async function validateOAuthJwt(token) {
+    // Config errors propagate (caller maps to 500). Token errors return reason.
+    const pair = await getKeyPair();
+    let header;
+    try {
+        header = decodeProtectedHeader(token);
+    }
+    catch {
+        return { ok: false, reason: "invalid" };
+    }
+    if (!header.kid || header.kid !== pair.kid) {
+        return { ok: false, reason: "unknown_key" };
+    }
+    let payload;
+    try {
+        ({ payload } = await jwtVerify(token, pair.key, {
+            algorithms: ["RS256"],
+            issuer: ISSUER,
+            audience: MCP_AUDIENCE,
+        }));
+    }
+    catch (e) {
+        if (e instanceof joseErrors.JWTExpired)
+            return { ok: false, reason: "expired" };
+        return { ok: false, reason: "invalid" };
+    }
+    if (typeof payload.sub !== "string" ||
+        typeof payload.scope !== "string" ||
+        typeof payload.grant_id !== "string" ||
+        typeof payload.client_id !== "string") {
+        return { ok: false, reason: "invalid" };
+    }
+    return {
+        ok: true,
+        claims: {
+            sub: payload.sub,
+            scope: payload.scope,
+            grant_id: payload.grant_id,
+            client_id: payload.client_id,
+        },
+    };
+}

package/dist/request-context.d.ts

@@ -0,0 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface McpRequestContext {
+    clientUserAgent?: string;
+}
+export declare const requestContext: AsyncLocalStorage<McpRequestContext>;

package/dist/request-context.js

@@ -0,0 +1,2 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const requestContext = new AsyncLocalStorage();

package/dist/tools.js

@@ -1,42 +1,72 @@
 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 { getStats, getTransactions, getPricePerM2, getDistricts, getLocations, getPriceHistogram, getTransactionsSummary, searchParcels, searchByPolygon, compareLocations, } from "./api-client.js";
+import { formatTransactionList, formatMarketOverview, formatPriceStats, formatHistogram, formatParcelResults, formatSpatialResults, formatCompareResults, formatLocationHierarchy, } from "./formatters.js";
 import { mapPropertyType, mapMarketType, mapUnitFunction, mapBuildingType, radiusKmToBbox, filterByLocation, expandDistrict, CITY_SUBDISTRICTS, } from "./mappings.js";
 // ── Helpers ─────────────────────────────────────────────────────────
+function sanitizeInput(s, maxLen = 50) {
+    return s.replace(/[<>]/g, "").slice(0, maxLen);
+}
 function textResponse(text) {
     return { content: [{ type: "text", text }] };
 }
 function formatCreditFooter(creditInfo) {
     if (!creditInfo)
         return "";
-    return `\n---\nTokeny API: ${creditInfo.balance} pozostało (koszt zapytania: ${creditInfo.cost})`;
+    return `\n---\nAPI tokens: ${creditInfo.balance} remaining (query cost: ${creditInfo.cost})`;
 }
 function requireApiKey(apiKey) {
     if (!apiKey) {
-        throw new Error("Authorization: Bearer <api-key> required. Get your free API key at https://cenogram.pl/api");
+        throw new Error("Internal: missing auth context. " +
+            "stdio: set CENOGRAM_API_KEY env var (key from https://cenogram.pl/api/keys). " +
+            "HTTP MCP: report bug - https://github.com/cenogram/mcp-server/issues");
     }
 }
-async function withErrorHandling(fn) {
+function extractKeyPrefix(apiKey) {
+    if (!apiKey)
+        return null;
+    if (apiKey.startsWith("\x01"))
+        return "oauth";
+    if (apiKey.startsWith("cngrm_"))
+        return apiKey.slice(0, 10);
+    return apiKey.slice(0, 4);
+}
+async function withErrorHandling(toolName, apiKey, fn) {
+    const start = Date.now();
+    let success = true;
     try {
         return await fn();
     }
     catch (error) {
+        success = false;
         const message = error instanceof Error ? error.message : String(error);
         return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
     }
+    finally {
+        process.stderr.write(JSON.stringify({
+            level: "info",
+            evt: "tool.call",
+            tool: toolName,
+            key_prefix: extractKeyPrefix(apiKey),
+            duration_ms: Date.now() - start,
+            success,
+        }) + "\n");
+    }
 }
 // ── Tool registration ──────────────────────────────────────────────
 export function registerTools(server, apiKey) {
     // ── Tool 1: search_transactions ─────────────────────────────────────
-    server.tool("search_transactions", `Search Polish real estate transactions from the national RCN registry (7M+ records).
+    server.tool("search_transactions", `Search Polish real estate transactions from the national RCN registry (8M+ records).
 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.`, {
+Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.
+Data notes: marketType is NULL for ~55% of records (notary didn't classify) - filtering by marketType excludes them. ~1.7% of records have no transaction_date.
+Location matches TERYT districts only - for neighborhoods (osiedla), use search_by_area instead.`, {
         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."),
+        teryt: z.string().min(1).optional().describe("TERYT administrative code(s) for precise area filtering. Comma-separated, max 10. 2-digit (voivodeship), 4-digit (county), 6-digit (municipality), or full precinct code (e.g. '321705_2.0054'). Use list_locations to find codes. More precise than 'location' - avoids name ambiguity."),
         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)"),
+            .describe("Market type: primary (developer) or secondary (resale). ~55% of records have unknown market type and will be excluded when this filter is used."),
         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()
@@ -60,10 +90,24 @@ Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.`, {
             .describe("Sort order (default: desc)"),
         page: z.number().min(1).default(1).optional()
             .describe("Page number for pagination (default: 1)"),
-    }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("search_transactions", apiKey, async () => {
         requireApiKey(apiKey);
+        if (params.teryt) {
+            const TERYT_RE = /^(\d{2}|\d{4}|\d{6}|\d{6}_\d|\d{6}_\d\.\d{4})$/;
+            const codes = params.teryt.split(",").map((c) => c.trim());
+            if (codes.length > 10) {
+                return textResponse("Too many TERYT codes (max 10). Narrow your selection.");
+            }
+            const invalid = codes.filter((c) => !TERYT_RE.test(c));
+            if (invalid.length > 0) {
+                return textResponse(`Invalid TERYT code(s): ${invalid.map((c) => `'${sanitizeInput(c)}'`).join(", ")}. ` +
+                    "Valid formats: 2-digit (voivodeship), 4-digit (county), 6-digit (municipality), " +
+                    "or precinct (e.g. '321705_2.0054'). Use list_locations to find codes.");
+            }
+        }
         const txParams = {
             district: params.location,
+            teryt: params.teryt,
             propertyType: mapPropertyType(params.propertyType),
             marketType: mapMarketType(params.marketType),
             unitFunction: mapUnitFunction(params.unitFunction),
@@ -92,9 +136,10 @@ 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.
-'Warszawa'/'Kraków'/'Łódź' auto-expand to all sub-districts (Warszawa=19, Kraków=5, Łódź=6). Other names use partial match.`, {
+'Warszawa'/'Kraków'/'Łódź' auto-expand to all sub-districts (Warszawa=19, Kraków=5, Łódź=6). Other names use partial match.
+Data quality: based on transaction prices from notarial deeds, not asking/listing prices. Coverage varies by county (some have data gaps of 5+ years).`, {
         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 () => {
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("get_price_statistics", apiKey, async () => {
         requireApiKey(apiKey);
         const { data: allRows, creditInfo } = await getPricePerM2(apiKey);
         let rows = allRows;
@@ -116,26 +161,27 @@ Useful for understanding the overall market price structure in Poland.`, {
             .describe("Number of price bins (5-50, default 20)"),
         maxPrice: z.number().default(3_000_000)
             .describe("Maximum price to include (default 3,000,000 PLN)"),
-    }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("get_price_distribution", apiKey, async () => {
         requireApiKey(apiKey);
         const { data: bins, creditInfo } = await getPriceHistogram(params.bins, params.maxPrice, apiKey);
         return textResponse(formatHistogram(bins) + formatCreditFooter(creditInfo));
     }));
     // ── 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).
-Area filters (minArea/maxArea) work for all propertyType values via COALESCE(usable_area_m2, parcel_area).`, {
+Best tool for neighborhood/osiedle searches (neighborhoods are not TERYT districts).
+Radius guide: 0.3-0.5 km for a street, 0.5-1 km for a neighborhood, 2-5 km for a city area.
+Example: apartments in Wrocław's Nowy Dwór (lat 51.143, lng 16.993, radiusKm=0.7).
+Area filters (minArea/maxArea) work for all propertyType values.`, {
         latitude: z.number().min(49).max(55)
             .describe("Latitude (Poland range: 49-55)"),
         longitude: z.number().min(14).max(25)
             .describe("Longitude (Poland range: 14-25)"),
         radiusKm: z.number().min(0.1).max(50).default(2)
-            .describe("Search radius in kilometers (0.1-50, default 2)"),
+            .describe("Search radius in km (0.1-50, default 2). Use 0.5-1 for neighborhoods, 0.3-0.5 for streets."),
         propertyType: z.enum(["land", "building", "developed_land", "unit"]).optional()
             .describe("Property type filter"),
         marketType: z.enum(["primary", "secondary"]).optional()
-            .describe("Market type filter"),
+            .describe("Market type: primary (developer) or secondary (resale). ~55% of records have unknown market type and will be excluded when this filter is used."),
         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()
@@ -150,7 +196,7 @@ Area filters (minArea/maxArea) work for all propertyType values via COALESCE(usa
         dateTo: z.string().optional().describe("End date (YYYY-MM-DD)"),
         limit: z.number().min(1).max(50).default(20)
             .describe("Number of results (1-50, default 20)"),
-    }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("search_by_area", apiKey, async () => {
         requireApiKey(apiKey);
         const bbox = radiusKmToBbox(params.latitude, params.longitude, params.radiusKm);
         const txParams = {
@@ -177,20 +223,37 @@ Area filters (minArea/maxArea) work for all propertyType values via COALESCE(usa
     }));
     // ── Tool 5: get_market_overview ─────────────────────────────────────
     server.tool("get_market_overview", `Get a comprehensive overview of the Polish real estate transaction database.
-Returns: total transaction count, date range, breakdown by property type and market type, top locations, price statistics.`, {}, { readOnlyHint: true }, async () => withErrorHandling(async () => {
+Returns: total transaction count, date range, breakdown by property type and market type, top locations, price statistics.
+Note: data quality varies by field - marketType is unknown for ~55% of records, transaction_date missing for ~1.7%.`, {}, { readOnlyHint: true }, async () => withErrorHandling("get_market_overview", apiKey, async () => {
         requireApiKey(apiKey);
         const { data: stats, creditInfo } = await getStats(apiKey);
         return textResponse(formatMarketOverview(stats) + formatCreditFooter(creditInfo));
     }));
     // ── Tool 6: list_locations ──────────────────────────────────────────
-    server.tool("list_locations", `List available locations (cities and districts) in the database.
-Returns administrative districts - for most cities, the district name equals the city name.
-For Warsaw: returns district names (Mokotów, Śródmieście, Wola, etc.), not 'Warszawa'.
-For Kraków: returns sub-districts (Kraków-Podgórze, Kraków-Śródmieście, etc.).
-Use the search parameter to filter by name.`, {
-        search: z.string().optional().describe("Filter locations by name (case-insensitive partial match, e.g. 'Krak' for Kraków districts)"),
-    }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+    server.tool("list_locations", `Browse locations in two modes:
+1. TERYT hierarchy (parent param): Navigate voivodeship → county → municipality → precinct. Returns TERYT codes for use in search_transactions(teryt=...).
+   - No parent: 16 voivodeships (2-digit codes)
+   - 2-digit: counties (4-digit), 4-digit: municipalities (6-digit), 6-digit: precincts
+2. Name search (search param): Find districts by name (flat list, legacy).
+If both provided, parent takes precedence.
+Use 'location' for quick city searches, 'teryt' for precise administrative filtering (avoids name ambiguity, e.g. 'Wałcz' is both a county and a municipality).`, {
+        parent: z.string().min(1).optional().describe("TERYT parent code to browse children. 2-digit (voivodeship → counties), 4-digit (county → municipalities), 6-digit (municipality → precincts). Omit for all voivodeships."),
+        search: z.string().min(1).optional().describe("Filter locations by name (case-insensitive partial match, e.g. 'Krak' for Kraków districts). Ignored when parent is set."),
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("list_locations", apiKey, async () => {
         requireApiKey(apiKey);
+        if (params.parent !== undefined) {
+            const parent = params.parent.trim();
+            if (!/^(\d{2}|\d{4}|\d{6})$/.test(parent)) {
+                return textResponse(`Invalid parent code '${sanitizeInput(parent)}'. Parent must be 2, 4, or 6 digits (e.g. '14' for Mazowieckie voivodeship). ` +
+                    "For precinct-level codes (e.g. '321705_2.0054'), use search_transactions(teryt=...) directly.");
+            }
+            const { data: locations, creditInfo } = await getLocations(parent, apiKey);
+            return textResponse(formatLocationHierarchy(locations, parent) + formatCreditFooter(creditInfo));
+        }
+        if (params.search === undefined) {
+            const { data: locations, creditInfo } = await getLocations(undefined, apiKey);
+            return textResponse(formatLocationHierarchy(locations) + formatCreditFooter(creditInfo));
+        }
         const { data: allDistricts, creditInfo } = await getDistricts(apiKey);
         let districts = allDistricts;
         if (params.search) {
@@ -203,7 +266,6 @@ Use the search parameter to filter by name.`, {
             return textResponse(msg + formatCreditFooter(creditInfo));
         }
         const lines = [`Found ${districts.length} locations:\n`];
-        // Show all if filtered, otherwise top 50
         const shown = params.search ? districts : districts.slice(0, 50);
         for (const d of shown) {
             lines.push(`  - ${d}`);
@@ -221,7 +283,7 @@ Example: search for parcels starting with '146518_8.01'.`, {
         q: z.string().min(3).describe("Parcel ID prefix to search for (min 3 chars). E.g. '146518_8.01'"),
         limit: z.number().min(1).max(10).default(10).optional()
             .describe("Max results (1-10, default 10)"),
-    }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("search_parcels", apiKey, async () => {
         requireApiKey(apiKey);
         const { data, creditInfo } = await searchParcels(params.q, params.limit, apiKey);
         return textResponse(formatParcelResults(data, params.q) + formatCreditFooter(creditInfo));
@@ -230,7 +292,7 @@ Example: search for parcels starting with '146518_8.01'.`, {
     server.tool("search_by_polygon", `Search real estate transactions within a geographic polygon.
 Provide a GeoJSON Polygon geometry to search within a custom area.
 Returns transactions found inside the polygon with coordinates.
-Use for precise area searches (neighborhoods, streets, custom regions).
+Use for precise neighborhood/osiedle boundaries. Can estimate coordinates from search_by_area results. For quick searches, start with search_by_area instead.
 Coordinates are [longitude, latitude]. First and last point must be identical.
 Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21],[21.0,52.21],[21.0,52.2]]]}`, {
         polygon: z.object({
@@ -257,7 +319,7 @@ Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21
         street: z.string().optional().describe("Street name filter (partial match)"),
         limit: z.number().min(1).max(5000).default(100).optional()
             .describe("Max results (1-5000, default 100). MCP displays up to 50 transactions."),
-    }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("search_by_polygon", apiKey, async () => {
         requireApiKey(apiKey);
         const { data, creditInfo } = await searchByPolygon({
             polygon: params.polygon,
@@ -302,7 +364,7 @@ Example: compare Mokotów, Wola, Ursynów for apartments.`, {
         minArea: z.number().optional().describe("Minimum area in m²"),
         maxArea: z.number().optional().describe("Maximum area in m²"),
         street: z.string().optional().describe("Street name filter"),
-    }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+    }, { readOnlyHint: true }, async (params) => withErrorHandling("compare_locations", apiKey, async () => {
         requireApiKey(apiKey);
         const { data, creditInfo } = await compareLocations({
             districts: params.districts,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cenogram/mcp-server",
-  "version": "0.1.6",
-  "description": "MCP Server for Polish real estate transaction data (7M+ transactions from RCN)",
+  "version": "0.2.0",
+  "description": "MCP Server for Polish real estate transaction data (8M+ transactions from RCN)",
   "type": "module",
   "bin": {
     "cenogram-mcp": "./dist/index.js"
@@ -20,6 +20,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
+    "jose": "^6.2.3",
+    "undici": "^5.29.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {