@cenogram/mcp-server 0.1.7 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function serverInstructions(): string;
 export declare function createMcpServer(apiKey?: string): McpServer;

package/dist/index.js

@@ -1,80 +1,179 @@
 #!/usr/bin/env node
+import { Sentry } from "./sentry.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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 { registerTools } from "./tools.js";
-// ── Node version check ─────────────────────────────────────────────
+import { fetch } from "undici";
+import { registerTools, experimentalToolsEnabled } from "./tools.js";
+import { dispatchAuth, sanitizeForLog } from "./auth-dispatch.js";
+import { requestContext } from "./request-context.js";
+import { signupUrl } from "./error-messages.js";
+import { channelSrc, isHttpMode } from "./transport-mode.js";
+function logAuth(payload, level) {
+    process.stderr.write(JSON.stringify({ level, ...payload }) + "\n");
+}
 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";
 try {
     PKG_VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
 }
-catch { /* fallback to hardcoded if dist/ used standalone */ }
-// ── Server factory ──────────────────────────────────────────────────
+catch { }
+export function serverInstructions() {
+    return [
+        "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ń, 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",
+        ...(experimentalToolsEnabled()
+            ? [
+                "- Rental yield: (experimental - may change/withdraw) list_rental_yield_locations (catalog of covered cities) → get_rental_yield(location|teryt) - indicative gross yield from asking rent vs RCN transaction prices. County level only (miasta na prawach powiatu), or Warszawa district via 6-digit teryt. For any name that is not a major city you know is covered, call the catalog FIRST or pass a county teryt - towns inside a larger powiat and non-Warszawa districts 404.",
+                "- Price spread: (experimental - may change/withdraw) list_price_spread_locations (catalog of covered cities) → get_price_spread(location|teryt) - asking-vs-transaction price spread %, marketType all|secondary|primary. County level only (miasta na prawach powiatu), or Warszawa district via 6-digit teryt. For any name that is not a major city you know is covered, call the catalog FIRST or pass a county teryt - towns inside a larger powiat and non-Warszawa districts 404.",
+            ]
+            : []),
+        "- Compare locations: list_locations → compare_locations (2-5 districts, requires at least one filter e.g. propertyType). Add includeDemographics=true for a GUS BDL block per district.",
+        "- Demographics & local stats: get_demographics(location|teryt) — GUS BDL indicators (population, economy, housing, planning, safety, education, prices). A city name resolves to county level; pass a 6/7-digit teryt for gmina-level detail.",
+        "- Parcel lookup: search_parcels(q, min 3 chars) → search_by_area (use returned lat/lng)",
+        "- Parcel resolve: resolve_parcel(parcelId | q | lat+lng) — turn a full parcel id, a UUID, a 'locality name + parcel number', or a coordinate into a concrete parcel; feed the returned id to search_transactions(parcelId) for its sale history.",
+        "- Per-building detail: search_transactions → get_building_breakdown(transaction_id) — footprint, storeys, est. total floor area per building (searches return per-transaction sums inline)",
+        "- Surroundings (nearby nuisances): search_transactions → get_transaction_surroundings(transaction_id) — per-plot distance to the nearest cemetery, landfill, sewage treatment plant, industrial/storage area, large industrial plant, and intensive livestock farm. A null distance = nothing within the search radius in reference data, never a guarantee.",
+        "- 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:",
+        "- Median/average prices are market-based: fractional ownership shares (share_basis=\"fraction\") and non-market deeds (public tenders, foreclosures, privileged/subsidized sales) are excluded from price aggregates. Transaction counts and coverage stay full. search_transactions/search_by_area flag fractional-share rows so you can spot which comparables are partial.",
+        "- price_per_m2 only meaningful for apartments (propertyType=\"unit\")",
+        "- Field provenance (search_transactions/search_by_area/search_by_polygon): per-record values are from the notarial deed (RCN) by default and carry no marker. Values we computed (parcel area summed across plots or converted from hectares; an inferred or reclassified property type) and approximated streets are flagged inline with a neutral [...] note — mirroring the \"Z RCN / Obliczone / Uzupełnione\" tiers on cenogram.pl. A field being absent from a result does NOT mean the deed omitted it: the county may simply not report that field.",
+        "- Rooms (izby) filter: search_transactions/search_by_area/search_by_polygon/compare_locations accept `rooms` (array, e.g. [\"2\",\"3\"]; \"8plus\" = 8 or more). Units only (propertyType=\"unit\"); rows with no room count are excluded. NOTE: RCN counts izby (chambers - a kitchen counts as one izba), so values run higher than portal \"pokoje\" listings.",
+        "- Floor (piętro) filter: the same tools accept `floor` (array, e.g. [\"0\",\"1\",\"2\"]; \"0\" = ground/parter, negatives = basement, \"10plus\" = 10 or more, \"0plus\" = ground and above, \"unknown\" = no floor recorded). Units only; this is the unit's floor, NOT the number of building storeys. Rows with no floor are excluded unless \"unknown\" is included.",
+        "- Results paginated (default 10-20). Use page parameter for more.",
+        `- For §79-compliant export table or interactive map - direct user to https://cenogram.pl/ceny-transakcyjne?src=${channelSrc()}`,
+        `- Deep link / permalink to the map: from a transaction's \`id\` and its \`Location: <A>°N, <B>°E\` line, build https://cenogram.pl/ceny-transakcyjne?src=${channelSrc()}#v=1&lat=<A>&lng=<B>&z=16&tx=<id> (drop the °N/°E; lat = the °N number, lng = the °E number) — opens that exact transaction on the map. Omit &tx=<id> for a link centered on the area without a specific row open.`,
+    ].join("\n");
+}
 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.",
-            "",
-            "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",
-            "",
-            "Workflows:",
-            "- Market analysis: get_market_overview → get_price_statistics(location) → search_transactions",
-            "- Compare locations: list_locations → compare_locations (2-5 districts, requires at least one filter e.g. propertyType)",
-            "- Parcel lookup: search_parcels(q, min 3 chars) → search_by_area (use returned lat/lng)",
-            "- 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",
-            "",
-            "Data notes:",
-            "- price_per_m2 only meaningful for apartments (propertyType=\"unit\")",
-            "- API has no rooms filter - use area as proxy (1-room: 20-35m², 2: 35-55m², 3: 55-90m², 4+: 80-130m²), then post-filter by rooms field in results",
-            "- Results paginated (default 10-20). Use page parameter for more.",
-            "- For §79-compliant export table or interactive map - direct user to cenogram.pl",
-        ].join("\n"),
-    });
+    const server = new McpServer({ name: "cenogram-mcp-server", version: PKG_VERSION }, { instructions: serverInstructions() });
     registerTools(server, apiKey);
     return server;
 }
-// ── Start ───────────────────────────────────────────────────────────
 async function main() {
-    const mode = process.argv.includes("--http") || process.env.MCP_TRANSPORT === "http" ? "http" : "stdio";
+    const mode = isHttpMode() ? "http" : "stdio";
     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");
                 }
@@ -83,6 +182,7 @@ async function main() {
                 }
             }
             catch (err) {
+                Sentry.captureException(err, { tags: { error_layer: "http_handler" } });
                 process.stderr.write(`HTTP error: ${String(err)}\n`);
                 if (!res.headersSent) {
                     res.writeHead(500, { "Content-Type": "application/json" }).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null }));
@@ -100,7 +200,7 @@ async function main() {
     else {
         if (!process.env.CENOGRAM_API_KEY) {
             process.stderr.write("Error: CENOGRAM_API_KEY is required.\n" +
-                "Get your free API key at https://cenogram.pl/api\n" +
+                `Get your free API key at ${signupUrl()}\n` +
                 "Then add it to your MCP config:\n" +
                 '  "env": { "CENOGRAM_API_KEY": "cngrm_..." }\n');
             process.exit(1);
@@ -110,7 +210,12 @@ async function main() {
     }
 }
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
-    main().catch((err) => {
+    process.on("SIGTERM", () => {
+        void Sentry.flush(2000).then(() => process.exit(0));
+    });
+    main().catch(async (err) => {
+        Sentry.captureException(err, { tags: { error_layer: "fatal" } });
+        await Sentry.flush(2000);
         process.stderr.write(`Fatal: ${String(err)}\n`);
         process.exit(1);
     });

package/dist/mappings.d.ts

@@ -3,13 +3,20 @@ export declare const MARKET_TYPES: Record<number, string>;
 export declare function mapPropertyType(value: string | undefined): number | undefined;
 export declare function mapMarketType(value: string | undefined): number | undefined;
 export declare const UNIT_FUNCTIONS: Record<number, string>;
-export declare function mapUnitFunction(value: string | undefined): number | undefined;
+export declare function mapUnitFunction(value: string | undefined): number | "unknown" | undefined;
 export declare const BUILDING_TYPES: Record<number, string>;
-export declare function mapBuildingType(value: string | undefined): number | undefined;
-/** Convert lat/lng/radius to bbox [minLng, minLat, maxLng, maxLat] (lng-first!) */
+export declare function mapBuildingType(value: string | undefined): number | "unknown" | undefined;
+export declare const OWNERSHIP_TYPES: Record<number, string>;
+export declare function mapOwnershipTypes(values: string[] | undefined): string | undefined;
+export declare const PARTY_TYPES: Record<number, string>;
+export declare const LAND_USES: Record<string, string>;
+export declare const TRANSACTION_TYPES: Record<number, string>;
+export declare function mapTransactionTypes(values: string[] | undefined): string | undefined;
 export declare function radiusKmToBbox(lat: number, lng: number, radiusKm: number): [number, number, number, number];
-/** Filter districts by location name (case-insensitive includes match) */
+export declare function stripDiacritics(s: string): string;
 export declare function filterByLocation(location: string, districts: string[]): string[];
 export declare const CITY_SUBDISTRICTS: ReadonlyMap<string, readonly string[]>;
-/** Returns sub-districts for known multi-district cities, or [district] for everything else. */
 export declare function expandDistrict(district: string): string[];
+export declare function buildNormalizedMap(districts: string[]): Map<string, string[]>;
+export declare function tryResolveCityKey(input: string): string[] | null;
+export declare function resolveDistrict(input: string, allDistricts: string[]): string[];

package/dist/mappings.js

@@ -1,4 +1,3 @@
-// ── Property & market type enum maps ────────────────────────────────
 export const PROPERTY_TYPES = {
     1: "Land (Grunt)",
     2: "Building (Budynek)",
@@ -29,7 +28,6 @@ export function mapMarketType(value) {
         return undefined;
     return MARKET_TYPE_MAP[value];
 }
-// ── Unit function enum maps ─────────────────────────────────────────
 export const UNIT_FUNCTIONS = {
     1: "Residential (Mieszkalna)",
     2: "Commercial (Handlowo-usługowa)",
@@ -45,13 +43,13 @@ const UNIT_FUNCTION_MAP = {
     production: 4,
     garage: 5,
     other: 6,
+    unknown: "unknown",
 };
 export function mapUnitFunction(value) {
     if (!value)
         return undefined;
     return UNIT_FUNCTION_MAP[value];
 }
-// ── Building type enum maps ─────────────────────────────────────────
 export const BUILDING_TYPES = {
     110: "Residential (Mieszkalny)",
     121: "Commercial (Handlowo-usługowy)",
@@ -75,33 +73,99 @@ const BUILDING_TYPE_MAP = {
     farm_utility: 127,
     hospital: 128,
     other_nonresidential: 129,
+    unknown: "unknown",
 };
 export function mapBuildingType(value) {
     if (!value)
         return undefined;
     return BUILDING_TYPE_MAP[value];
 }
-// ── Bbox conversion ─────────────────────────────────────────────────
-/** Convert lat/lng/radius to bbox [minLng, minLat, maxLng, maxLat] (lng-first!) */
+export const OWNERSHIP_TYPES = {
+    1: "Land ownership",
+    2: "Perpetual usufruct",
+    3: "Cooperative ownership right",
+    4: "Unit sale",
+    5: "Ownership",
+    6: "Unit ownership with appurtenant right",
+    7: "Building ownership with appurtenant right",
+    8: "Perpetual usufruct",
+};
+const OWNERSHIP_TYPE_FILTER_MAP = {
+    land_ownership: "1",
+    perpetual_usufruct: "2,8",
+    cooperative_ownership: "3",
+    unit_sale: "4",
+    ownership: "5",
+    unit_ownership_with_appurtenant_right: "6",
+    building_ownership_with_appurtenant_right: "7",
+    unknown: "unknown",
+};
+export function mapOwnershipTypes(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const codes = values.map((v) => OWNERSHIP_TYPE_FILTER_MAP[v]).filter(Boolean);
+    return codes.length > 0 ? codes.join(",") : undefined;
+}
+export const PARTY_TYPES = {
+    1: "State Treasury",
+    2: "Local-government unit",
+    3: "Natural person",
+    4: "Legal person",
+    5: "Cooperative",
+    6: "State legal person",
+    7: "Other legal person",
+};
+export const LAND_USES = {
+    gruntyZabudowaneIZurbanizowane: "Built-up and urbanized land",
+    gruntyRolne: "Agricultural land",
+    gruntyLesne: "Forest land",
+    terenyKomunikacyjne: "Transport land",
+    inne: "Other",
+};
+export const TRANSACTION_TYPES = {
+    1: "Free market (Wolny rynek)",
+    3: "Auction (Przetargowa)",
+    4: "Non-auction (Bezprzetargowa)",
+    5: "Subsidized (Z bonifikatą)",
+    9: "Public purpose (Na cel publiczny)",
+    10: "Foreclosure (Egzekucyjna)",
+};
+const TRANSACTION_TYPE_MAP = {
+    free_market: 1,
+    auction: 3,
+    non_auction: 4,
+    subsidized: 5,
+    public_purpose: 9,
+    foreclosure: 10,
+    unknown: "unknown",
+};
+export function mapTransactionTypes(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const mapped = values
+        .map(v => TRANSACTION_TYPE_MAP[v])
+        .filter((v) => v !== undefined);
+    if (mapped.length === 0)
+        return undefined;
+    return mapped.join(",");
+}
 export function radiusKmToBbox(lat, lng, radiusKm) {
     const latDelta = radiusKm / 111.0;
     const lngDelta = radiusKm / (111.0 * Math.cos((lat * Math.PI) / 180));
     return [
-        lng - lngDelta, // minLng
-        lat - latDelta, // minLat
-        lng + lngDelta, // maxLng
-        lat + latDelta, // maxLat
+        lng - lngDelta,
+        lat - latDelta,
+        lng + lngDelta,
+        lat + latDelta,
     ];
 }
-// ── Location filtering ──────────────────────────────────────────────
-/** Filter districts by location name (case-insensitive includes match) */
+export function stripDiacritics(s) {
+    return s.normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[łŁ]/g, (c) => c === "ł" ? "l" : "L");
+}
 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",
@@ -115,7 +179,61 @@ export const CITY_SUBDISTRICTS = new Map([
             "Łódź", "Łódź-Bałuty", "Łódź-Górna", "Łódź-Polesie", "Łódź-Śródmieście", "Łódź-Widzew",
         ]],
 ]);
-/** Returns sub-districts for known multi-district cities, or [district] for everything else. */
 export function expandDistrict(district) {
     return CITY_SUBDISTRICTS.get(district)?.slice() ?? [district];
 }
+export function buildNormalizedMap(districts) {
+    const map = new Map();
+    for (const d of districts) {
+        const key = stripDiacritics(d.toLowerCase());
+        const existing = map.get(key);
+        if (existing) {
+            existing.push(d);
+        }
+        else {
+            map.set(key, [d]);
+        }
+    }
+    for (const [cityName] of CITY_SUBDISTRICTS) {
+        const key = stripDiacritics(cityName.toLowerCase());
+        if (!map.has(key)) {
+            map.set(key, [cityName]);
+        }
+    }
+    return map;
+}
+let lastDistricts = null;
+let normalizedMap = null;
+function getNormalizedMap(districts) {
+    if (districts !== lastDistricts) {
+        normalizedMap = buildNormalizedMap(districts);
+        lastDistricts = districts;
+    }
+    return normalizedMap;
+}
+export function tryResolveCityKey(input) {
+    const normalized = stripDiacritics(input.trim().toLowerCase());
+    for (const [cityName, subs] of CITY_SUBDISTRICTS) {
+        if (stripDiacritics(cityName.toLowerCase()) === normalized) {
+            return subs.slice();
+        }
+    }
+    return null;
+}
+export function resolveDistrict(input, allDistricts) {
+    const city = tryResolveCityKey(input);
+    if (city)
+        return city;
+    const normalized = stripDiacritics(input.trim().toLowerCase());
+    const map = getNormalizedMap(allDistricts);
+    const canonicals = map.get(normalized);
+    if (canonicals) {
+        const result = [];
+        for (const c of canonicals) {
+            const expanded = expandDistrict(c);
+            result.push(...expanded);
+        }
+        return result;
+    }
+    return [input];
+}

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,63 @@
+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/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 };
+}
+export async function validateOAuthJwt(token) {
+    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/sentry-scrub.d.ts

@@ -0,0 +1,2 @@
+export declare function scrubHeaders(headers: Record<string, string>): Record<string, string>;
+export declare function scrubString(s: string): string;

package/dist/sentry-scrub.js

@@ -0,0 +1,14 @@
+const SENSITIVE_HEADERS = new Set([
+    "authorization", "cookie", "x-internal-auth", "x-api-key",
+]);
+const API_KEY_PATTERN = /cngrm_[a-f0-9]+/g;
+export function scrubHeaders(headers) {
+    const scrubbed = {};
+    for (const [key, value] of Object.entries(headers)) {
+        scrubbed[key] = SENSITIVE_HEADERS.has(key.toLowerCase()) ? "[Filtered]" : value;
+    }
+    return scrubbed;
+}
+export function scrubString(s) {
+    return s.replace(API_KEY_PATTERN, "[Filtered]");
+}

package/dist/sentry.d.ts

@@ -0,0 +1,2 @@
+import * as Sentry from "@sentry/node";
+export { Sentry };

package/dist/sentry.js

@@ -0,0 +1,29 @@
+import * as Sentry from "@sentry/node";
+import { scrubHeaders, scrubString } from "./sentry-scrub.js";
+Sentry.init({
+    dsn: process.env.SENTRY_DSN,
+    environment: process.env.NODE_ENV || "development",
+    release: process.env.GIT_SHA || "unknown",
+    enabled: process.env.NODE_ENV === "production" && !!process.env.SENTRY_DSN,
+    tracesSampleRate: 0,
+    profilesSampleRate: 0,
+    initialScope: {
+        tags: { service: "mcp" },
+    },
+    beforeSend(event) {
+        if (event.request?.headers) {
+            event.request.headers = scrubHeaders(event.request.headers);
+        }
+        if (event.request?.url) {
+            event.request.url = scrubString(event.request.url);
+        }
+        if (event.exception?.values) {
+            for (const ex of event.exception.values) {
+                if (ex.value)
+                    ex.value = scrubString(ex.value);
+            }
+        }
+        return event;
+    },
+});
+export { Sentry };

package/dist/tools.d.ts

@@ -1,2 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function experimentalToolsEnabled(): boolean;
 export declare function registerTools(server: McpServer, apiKey?: string): void;