@cenogram/mcp-server 0.6.0 → 0.11.0

package/dist/index.d.ts

@@ -2,3 +2,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function serverInstructions(): string;
 export declare function createMcpServer(apiKey?: string): McpServer;
+export declare function handleHttpRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse): Promise<void>;

package/dist/index.js

@@ -29,12 +29,13 @@ 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.",
+        "CRITICAL - Addressing a place (resolve the name to a code first):",
+        "- To point at a place, resolve its name to a code: list_locations(search=\"name\") returns a TERYT code for every match; pass that as search_transactions(teryt=code) for filtering that carries no name ambiguity.",
+        "- The name is a parallel path, not a fallback. A match the result flags as an RCN district (and any match that has no TERYT code) also accepts its name directly as search_transactions(location=name). Use location= only for a name a result handed you, never one you guessed.",
         "- 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.",
+        "- Neighborhoods/osiedla (Nowy Dwór, Oliwa, Jeżyce) are usually NOT TERYT districts - three cases: (a) if the name is an administrative unit or cadastral precinct, list_locations(search=name) returns its teryt, use that; (b) for a precinct name PLUS a parcel number, resolve_parcel(q=\"name number\") turns the pair into one parcel; (c) for a true neighbourhood outside TERYT, get coordinates FROM THE USER and pass them to search_by_area (radiusKm 0.5-1.0), then refine with search_by_polygon - never invent coordinates. resolve_parcel does not resolve a bare neighbourhood name; it needs a name and a parcel number.",
         "- 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.",
         "",
@@ -44,14 +45,17 @@ export function serverInstructions() {
             ? [
                 "- 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.",
+                "- Flood-hazard exposure: (experimental - may change/withdraw) list_flood_risk_locations (catalog of covered counties) → get_flood_risk(location|teryt) - share of a county's transactions on land in a mapped flood-hazard zone, by severity (return periods). County level, all-time. Counts a mapped zone only; absence is never asserted as 'safe'. For any name that is not a major city you know is covered, call the catalog FIRST or pass a county teryt.",
             ]
             : []),
         "- 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 lookup: search_parcels(q, min 3 chars) → get_parcel_report(parcelId) for everything on the parcel, or search_transactions(parcelId) for its sale history.",
+        "- Find parcels in an area: list_parcels_in_area (name it with teryt, location, bbox or a circle) filtered by street, buildingNumber, minArea, maxArea → get_parcel_land_class for the soil class of one you pick, or get_parcel_report for everything on it.",
         "- 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.",
+        "- 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, intensive livestock farm, and overhead high-voltage and extra-high-voltage power line. A null distance = nothing within the search radius in reference data, never a guarantee.",
+        "- Road access: search_transactions → get_transaction_roads(transaction_id) — per-plot distance to the nearest public road (with its category, class and the estimated distance to the carriageway edge), to the nearest road of any kind, and to the nearest motorway/expressway/dual-carriageway, plus a three-state access_indicator. It is geometric evidence from carriageway centrelines, NOT a determination of legal access - easements and rights of way live in the land register and are not published here.",
         "- 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",
@@ -73,11 +77,130 @@ export function createMcpServer(apiKey) {
     registerTools(server, apiKey);
     return server;
 }
+export async function handleHttpRequest(req, res) {
+    try {
+        const pathname = req.url?.split("?")[0];
+        if (pathname === "/mcp") {
+            const dispatch = await dispatchAuth(req.headers.authorization);
+            if (dispatch.kind === "passthrough") {
+                logAuth(dispatch.log, "info");
+            }
+            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;
+            }
+            if (req.method === "GET") {
+                res.writeHead(405, { Allow: "POST, DELETE", "Content-Type": "application/json" }).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed." }, id: null }));
+                return;
+            }
+            const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
+            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" || pathname === "/.well-known/oauth-protected-resource/mcp") {
+            const resource = pathname.endsWith("/mcp") ? "https://mcp.cenogram.pl/mcp" : "https://mcp.cenogram.pl";
+            res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "public, max-age=3600" }).end(JSON.stringify({
+                resource,
+                authorization_servers: ["https://api.cenogram.pl"],
+                scopes_supported: ["mcp"],
+                bearer_methods_supported: ["header"],
+            }));
+        }
+        else if (pathname === "/.well-known/glama.json") {
+            const maintainer = process.env.GLAMA_MAINTAINER_EMAIL;
+            if (!maintainer) {
+                res.writeHead(404, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "not_found" }));
+            }
+            else {
+                res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "public, max-age=3600" }).end(JSON.stringify({
+                    $schema: "https://glama.ai/mcp/schemas/connector.json",
+                    maintainers: [{ email: maintainer }],
+                }));
+            }
+        }
+        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");
+        }
+        else {
+            res.writeHead(404).end();
+        }
+    }
+    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 }));
+        }
+    }
+}
 async function main() {
     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");
@@ -87,121 +210,6 @@ async function main() {
                 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 dispatch = await dispatchAuth(req.headers.authorization);
-                    if (dispatch.kind === "passthrough") {
-                        logAuth(dispatch.log, "info");
-                    }
-                    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" || pathname === "/.well-known/oauth-protected-resource/mcp") {
-                    const resource = pathname.endsWith("/mcp") ? "https://mcp.cenogram.pl/mcp" : "https://mcp.cenogram.pl";
-                    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "public, max-age=3600" }).end(JSON.stringify({
-                        resource,
-                        authorization_servers: ["https://api.cenogram.pl"],
-                        scopes_supported: ["mcp"],
-                        bearer_methods_supported: ["header"],
-                    }));
-                }
-                else if (pathname === "/.well-known/glama.json") {
-                    const maintainer = process.env.GLAMA_MAINTAINER_EMAIL;
-                    if (!maintainer) {
-                        res.writeHead(404, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "not_found" }));
-                    }
-                    else {
-                        res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "public, max-age=3600" }).end(JSON.stringify({
-                            $schema: "https://glama.ai/mcp/schemas/connector.json",
-                            maintainers: [{ email: maintainer }],
-                        }));
-                    }
-                }
-                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");
-                }
-                else {
-                    res.writeHead(404).end();
-                }
-            }
-            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 }));
-                }
-            }
-        };
         createServer((req, res) => {
             handleHttpRequest(req, res).catch((err) => {
                 process.stderr.write(`Unhandled HTTP error: ${String(err)}\n`);