@cenogram/mcp-server 0.1.7 → 0.5.0

package/dist/api-client.js

@@ -1,6 +1,24 @@
 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";
+export function getDemographics(params, apiKey) {
+    return fetchApi("/api/v1/demographics", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+        year: params.year,
+        yearFrom: params.yearFrom,
+        yearTo: params.yearTo,
+        category: params.category,
+    }), apiKey);
+}
+export function getInfrastructureSignals(params, apiKey) {
+    return fetchApi("/api/v1/infrastructure-signals", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+    }), apiKey);
+}
 function extractCreditInfo(res) {
     if (!res.headers)
         return null;
@@ -10,29 +28,81 @@ function extractCreditInfo(res) {
         return null;
     return { balance, cost };
 }
-// ── Shared HTTP helpers ────────────────────────────────────────────
+export const OAUTH_CTX_PREFIX = "\x01";
+export function encodeOAuthCtx(userId, grantId) {
+    return `${OAUTH_CTX_PREFIX}${userId}${OAUTH_CTX_PREFIX}${grantId}`;
+}
+export function decodeOAuthCtx(key) {
+    if (!key.startsWith(OAUTH_CTX_PREFIX))
+        return null;
+    const rest = key.slice(OAUTH_CTX_PREFIX.length);
+    const sepIdx = rest.indexOf(OAUTH_CTX_PREFIX);
+    if (sepIdx <= 0)
+        return null;
+    const grantId = rest.slice(sepIdx + OAUTH_CTX_PREFIX.length);
+    if (!grantId)
+        return null;
+    return { userId: rest.slice(0, sepIdx), grantId };
+}
 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`);
-    }
+export function parseRetryAfterSeconds(headerValue) {
+    if (!headerValue)
+        return null;
+    const raw = headerValue.trim();
+    if (/^\d+$/.test(raw))
+        return Math.max(1, parseInt(raw, 10));
+    if (!/[A-Za-z]/.test(raw))
+        return null;
+    const asDate = Date.parse(raw);
+    if (Number.isNaN(asDate))
+        return null;
+    return Math.max(1, Math.ceil((asDate - Date.now()) / 1000));
+}
+export function formatRetryAfter(seconds) {
+    const unit = (value, name) => `${value} ${name}${value === 1 ? "" : "s"}`;
+    if (seconds < 60)
+        return unit(seconds, "second");
+    if (seconds < 3600)
+        return unit(Math.ceil(seconds / 60), "minute");
+    if (seconds < 86400)
+        return unit(Math.ceil(seconds / 3600), "hour");
+    return unit(Math.ceil(seconds / 86400), "day");
+}
+async function handleErrorResponse(res, apiKey) {
     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 seconds = parseRetryAfterSeconds(res.headers?.get?.("Retry-After"));
+        const wait = seconds !== null ? ` Retry in ${formatRetryAfter(seconds)}.` : " Retry shortly.";
+        throw new Error(`Too many requests - this is a rate limit, not an exhausted allowance.${wait}`);
     }
-    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 = {};
@@ -42,7 +112,6 @@ function toQueryParams(obj) {
     }
     return params;
 }
-// ── HTTP client ─────────────────────────────────────────────────────
 export async function fetchApi(path, params, apiKey) {
     const url = new URL(path, BASE_URL);
     if (params) {
@@ -56,7 +125,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 {
@@ -77,28 +146,35 @@ 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 {
         clearTimeout(timeout);
     }
 }
-// ── Typed wrappers ──────────────────────────────────────────────────
 export function getStats(apiKey) {
-    return fetchApi("/api/stats", undefined, apiKey);
+    return fetchApi("/api/v1/stats", undefined, apiKey);
 }
 export function getTransactions(p, apiKey) {
-    return fetchApi("/api/transactions", toQueryParams({
+    return fetchApi("/api/v1/transactions", toQueryParams({
         district: p.district,
+        teryt: p.teryt,
         street: p.street,
         buildingNumber: p.buildingNumber,
         parcelId: p.parcelId,
         propertyType: p.propertyType,
         marketType: p.marketType,
         unitFunction: p.unitFunction,
+        ownershipType: p.ownershipType,
         buildingType: p.buildingType,
         mpzpDesignation: p.mpzpDesignation,
+        transactionType: p.transactionType,
+        rooms: p.rooms,
+        floor: p.floor,
+        floodRisk: p.floodRisk,
+        heritageStatus: p.heritageStatus,
+        landslideRisk: p.landslideRisk,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -113,14 +189,24 @@ export function getTransactions(p, apiKey) {
     }), apiKey);
 }
 export function getTransactionsSummary(p, apiKey) {
-    return fetchApi("/api/transactions/summary", toQueryParams({
+    return fetchApi("/api/v1/transactions/summary", toQueryParams({
         district: p.district,
+        teryt: p.teryt,
         street: p.street,
+        buildingNumber: p.buildingNumber,
+        parcelId: p.parcelId,
         propertyType: p.propertyType,
         marketType: p.marketType,
         unitFunction: p.unitFunction,
+        ownershipType: p.ownershipType,
         buildingType: p.buildingType,
         mpzpDesignation: p.mpzpDesignation,
+        transactionType: p.transactionType,
+        rooms: p.rooms,
+        floor: p.floor,
+        floodRisk: p.floodRisk,
+        heritageStatus: p.heritageStatus,
+        landslideRisk: p.landslideRisk,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -131,16 +217,67 @@ export function getTransactionsSummary(p, apiKey) {
     }), apiKey);
 }
 export function getPricePerM2(apiKey) {
-    return fetchApi("/api/price-per-m2", undefined, apiKey);
+    return fetchApi("/api/v1/price-per-m2", undefined, apiKey);
 }
 export function getDistricts(apiKey) {
-    return fetchApi("/api/districts", undefined, apiKey);
+    return fetchApi("/api/v1/districts", undefined, apiKey);
+}
+export function getRentalYield(params, apiKey) {
+    return fetchApi("/api/v1/rental-yield", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+        areaBucket: params.areaBucket,
+    }), apiKey);
+}
+export function getRentalYieldLocations(params, apiKey) {
+    return fetchApi("/api/v1/rental-yield/locations", toQueryParams({
+        search: params.search,
+    }), apiKey);
+}
+export function getPriceSpread(params, apiKey) {
+    return fetchApi("/api/v1/price-spread", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+        marketType: params.marketType,
+        areaBucket: params.areaBucket,
+    }), apiKey);
+}
+export function getPriceSpreadLocations(params, apiKey) {
+    return fetchApi("/api/v1/price-spread/locations", toQueryParams({
+        search: params.search,
+    }), apiKey);
+}
+export function getValuation(params, apiKey) {
+    return fetchApi("/api/v1/valuations", toQueryParams({
+        lat: params.lat,
+        lng: params.lng,
+        parcelId: params.parcelId,
+        area: params.area,
+        rooms: params.rooms,
+        market: params.market,
+        includeComps: params.includeComps ? "true" : undefined,
+    }), apiKey);
+}
+export function getLocations(parent, apiKey) {
+    return fetchApi("/api/v1/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);
+    return fetchApi("/api/v1/stats/price-histogram", toQueryParams({ bins, max }), apiKey);
 }
 export function searchParcels(q, limit, apiKey) {
-    return fetchApi("/api/parcels/search", toQueryParams({ q, limit }), apiKey);
+    return fetchApi("/api/v1/parcels/search", toQueryParams({ q, limit }), apiKey);
+}
+export function resolveParcel(params, apiKey) {
+    return fetchApi("/api/v1/parcels/resolve", toQueryParams({
+        q: params.q,
+        parcelId: params.parcelId,
+        lat: params.lat,
+        lng: params.lng,
+    }), apiKey);
+}
+export function getParcelReport(parcelKey, apiKey) {
+    const urlKey = parcelKey.trim().replace(/\//g, "-");
+    return fetchApi(`/api/v1/parcels/${encodeURIComponent(urlKey)}/report`, undefined, apiKey);
 }
 export function searchByPolygon(p, apiKey) {
     const body = { polygon: p.polygon };
@@ -152,6 +289,8 @@ export function searchByPolygon(p, apiKey) {
         body.unitFunction = p.unitFunction;
     if (p.buildingType != null)
         body.buildingType = p.buildingType;
+    if (p.ownershipType != null)
+        body.ownershipType = p.ownershipType;
     if (p.mpzpDesignation)
         body.mpzpDesignation = p.mpzpDesignation;
     if (p.minPrice != null)
@@ -170,18 +309,29 @@ export function searchByPolygon(p, apiKey) {
         body.district = p.district;
     if (p.street)
         body.street = p.street;
+    if (p.transactionType)
+        body.transactionType = p.transactionType;
+    if (p.rooms)
+        body.rooms = p.rooms;
+    if (p.floor)
+        body.floor = p.floor;
     if (p.limit != null)
         body.limit = p.limit;
-    return fetchApiPost("/api/transactions/spatial", body, apiKey);
+    return fetchApiPost("/api/v1/transactions/spatial", body, apiKey);
 }
 export function compareLocations(p, apiKey) {
-    return fetchApi("/api/transactions/summary/compare", toQueryParams({
+    return fetchApi("/api/v1/transactions/summary/compare", toQueryParams({
         districts: p.districts,
+        include: p.include,
         propertyType: p.propertyType,
         marketType: p.marketType,
         unitFunction: p.unitFunction,
+        ownershipType: p.ownershipType,
         buildingType: p.buildingType,
         mpzpDesignation: p.mpzpDesignation,
+        transactionType: p.transactionType,
+        rooms: p.rooms,
+        floor: p.floor,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -191,3 +341,30 @@ export function compareLocations(p, apiKey) {
         street: p.street,
     }), apiKey);
 }
+export function getBuildingBreakdown(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/buildings`, undefined, apiKey);
+}
+export function getTransactionFlood(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/flood`, undefined, apiKey);
+}
+export function getTransactionHeritage(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/heritage`, undefined, apiKey);
+}
+export function getTransactionLandslide(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/landslide`, undefined, apiKey);
+}
+export function getTransactionSurroundings(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/surroundings`, undefined, apiKey);
+}
+export function getTransactionTransit(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/transit`, undefined, apiKey);
+}
+export function getTransactionPermits(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/permits`, undefined, apiKey);
+}
+export function getTransactionPlanning(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/planning`, undefined, apiKey);
+}
+export function getTransactionFarmland(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/farmland`, undefined, 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,141 @@
+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";
+const QUOTED_RE = /^[\x20\x21\x23-\x5B\x5D-\x7E]*$/;
+const BEARER_RE = /^Bearer[ \t]+(.+)$/i;
+const JWT_SHAPE_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+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")}`);
+}
+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) {
+    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 },
+        };
+    }
+    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 },
+        };
+    }
+    if (rawToken.startsWith("cngrm_")) {
+        return {
+            kind: "passthrough",
+            apiKey: rawToken,
+            log: { evt: "auth.passthrough", mode: "api_key", key_prefix: sanitizeForLog(rawToken.slice(0, 10)) },
+        };
+    }
+    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 },
+        };
+    }
+    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) {
+        let headerKid = null;
+        try {
+            const headerJson = JSON.parse(Buffer.from(rawToken.split(".")[0], "base64url").toString("utf-8"));
+            headerKid = safeKid(headerJson.kid);
+        }
+        catch {
+        }
+        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),
+        log: { evt: "auth.passthrough", mode: "oauth", grant_id: sanitizeForLog(result.claims.grant_id) },
+    };
+}

package/dist/client-id.js

@@ -8,12 +8,10 @@ let cachedId = null;
 export function getClientId() {
     if (cachedId)
         return cachedId;
-    // Allow override via env var
     if (process.env.CENOGRAM_CLIENT_ID?.trim()) {
         cachedId = process.env.CENOGRAM_CLIENT_ID.trim();
         return cachedId;
     }
-    // Try reading persisted ID
     try {
         const stored = readFileSync(CLIENT_ID_FILE, "utf-8").trim();
         if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(stored)) {
@@ -22,16 +20,13 @@ export function getClientId() {
         }
     }
     catch {
-        // File doesn't exist or isn't readable - generate new
     }
-    // Generate and persist
     const id = randomUUID();
     try {
         mkdirSync(CONFIG_DIR, { recursive: true });
         writeFileSync(CLIENT_ID_FILE, id + "\n", { mode: 0o600 });
     }
     catch {
-        // Read-only fs (Docker, sandbox) - use ephemeral ID
     }
     cachedId = id;
     return id;

package/dist/error-messages.d.ts

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

package/dist/error-messages.js

@@ -0,0 +1,80 @@
+import { channelSrc } from "./transport-mode.js";
+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 signupUrl() {
+    return `https://cenogram.pl/api?src=${channelSrc()}`;
+}
+function specificMessage(body) {
+    const rawError = typeof body.error === "string" ? body.error.trim() : "";
+    const rawMessage = typeof body.message === "string" ? body.message.trim() : "";
+    const candidate = rawMessage || rawError;
+    return candidate.length > 0 && candidate.length <= 500 ? candidate : "";
+}
+function sentence(text) {
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+function specificField(value) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim();
+    return trimmed.length > 0 && trimmed.length <= 500 ? trimmed : "";
+}
+export function authErrorMessage(status, mode, body = {}) {
+    const specific = specificMessage(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.";
+            }
+            if (mode === "none") {
+                return (`No Cenogram API key configured. Get a free key at ${signupUrl()}, ` +
+                    "then set it as the CENOGRAM_API_KEY environment variable of this MCP server.");
+            }
+            return "API key rejected. Check https://cenogram.pl/ustawienia#api-keys if it's still active.";
+        case 402: {
+            const explanation = specificField(body.message);
+            if (body.error === "trial_expired" && explanation) {
+                const upgrade = specificField(body.upgrade);
+                return upgrade && !explanation.includes(upgrade) ? `${sentence(explanation)} (${upgrade})` : explanation;
+            }
+            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?src=${channelSrc()}#cennik`;
+            }
+            return `Insufficient credits for key's account (balance: ${balance}, query cost: ${required}). Top up: https://cenogram.pl/api?src=${channelSrc()}#cennik`;
+        }
+        case 403:
+            if (body.error === "email_not_verified") {
+                return "Account email not verified. Check your inbox, click the activation link, then retry.";
+            }
+            return specific ? `Access denied: ${specific}` : "Access denied (HTTP 403).";
+        case 503: {
+            if (!specific)
+                return "Cenogram temporarily unavailable. Try again shortly.";
+            const saysRetry = /try again|retry|spr[oó]buj ponownie/i.test(specific);
+            return `Cenogram temporarily unavailable: ${sentence(specific)}${saysRetry ? "" : " Try again shortly."}`;
+        }
+        case 410: {
+            const successor = specificField(body.successor);
+            const reason = sentence(specific || "This endpoint has been retired.");
+            const where = successor ? ` It was replaced by ${successor}.` : "";
+            return `${reason}${where} This is permanent - retrying will not help. Update @cenogram/mcp-server to the latest version.`;
+        }
+        case 404:
+            return specific || "Not found (HTTP 404). Check the location name or TERYT code.";
+        case 400:
+        case 422:
+            return specific ? `Invalid request: ${specific}` : `Invalid request (HTTP ${status}). Check parameters.`;
+        default:
+            return `Cenogram API unavailable (HTTP ${status}). Try again shortly.`;
+    }
+}