@cenogram/mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -20,12 +20,12 @@ Manage your keys at [cenogram.pl/ustawienia](https://cenogram.pl/ustawienia).
 
 ## Installation
 
-Pick your client. All options below use the hosted server — no local install needed (except npx/stdio).
+Pick your client. All options below use the hosted server - no local install needed (except npx/stdio).
 
 <details open>
 <summary><strong>Claude Code</strong></summary>
 
-One command — zero config files:
+One command - zero config files:
 
 ```bash
 claude mcp add cenogram https://mcp.cenogram.pl/mcp \
@@ -77,7 +77,7 @@ Add to your config file:
 }
 ```
 
-**Stdio fallback** (older versions — requires Node.js >= 18):
+**Stdio fallback** (older versions - requires Node.js >= 18):
 ```json
 {
   "mcpServers": {
@@ -159,7 +159,7 @@ In VS Code: Settings > Cline > MCP Servers. Add:
 </details>
 
 <details>
-<summary><strong>npx (stdio) — local/offline</strong></summary>
+<summary><strong>npx (stdio) - local/offline</strong></summary>
 
 Requires **Node.js >= 18**. Use this if you want to run the server locally instead of connecting to the hosted one.
 
@@ -191,7 +191,7 @@ Requires **Node.js >= 18**. Use this if you want to run the server locally inste
 
 | Env Variable | Required | Default | Description |
 |---|---|---|---|
-| `CENOGRAM_API_KEY` | **Yes** (stdio) | — | API key from [cenogram.pl/api](https://cenogram.pl/api) |
+| `CENOGRAM_API_KEY` | **Yes** (stdio) | - | API key from [cenogram.pl/api](https://cenogram.pl/api) |
 | `CENOGRAM_API_URL` | No | `https://cenogram.pl` | API base URL |
 | `MCP_TRANSPORT` | No | `stdio` | Set to `http` for Streamable HTTP mode |
 | `MCP_PORT` | No | `3002` | HTTP server port (HTTP mode only) |
@@ -235,7 +235,7 @@ You can also use the `--http` CLI flag instead of `MCP_TRANSPORT=http`.
 
 - Most cities: use the city name directly (e.g., "Gdansk", "Lublin")
 - Warsaw: use district names ("Mokotow", "Srodmiescie", "Wola") -- "Warszawa" won't match
-- Krakow: use sub-districts ("Krakow-Podgorze", "Krakow-Srodmiescie") — plain "Krakow" won't match
+- Krakow: use sub-districts ("Krakow-Podgorze", "Krakow-Srodmiescie") - plain "Krakow" won't match
 - Use `list_locations` to find valid names
 
 ### Property types
@@ -269,13 +269,13 @@ This mimics how a property appraiser finds comparable transactions for valuation
 
 ## Troubleshooting
 
-**"Error: CENOGRAM_API_KEY is required"** — This only applies to stdio mode. Make sure `CENOGRAM_API_KEY` is set in the `env` block of your MCP config. For HTTP remote, the key goes in the `Authorization` header instead.
+**"Error: CENOGRAM_API_KEY is required"** - This only applies to stdio mode. Make sure `CENOGRAM_API_KEY` is set in the `env` block of your MCP config. For HTTP remote, the key goes in the `Authorization` header instead.
 
-**npx hangs or fails** — Check your Node.js version with `node -v`. The stdio mode requires Node.js >= 18. If you're on an older version, use the HTTP remote option instead (no Node.js needed).
+**npx hangs or fails** - Check your Node.js version with `node -v`. The stdio mode requires Node.js >= 18. If you're on an older version, use the HTTP remote option instead (no Node.js needed).
 
-**"Warszawa" returns 0 results** — Warsaw uses district names (Mokotow, Wola, Srodmiescie, Bemowo, etc.). Use `list_locations(search="warsz")` to find valid names. Same applies to Krakow (use "Krakow-Podgorze", "Krakow-Srodmiescie", etc.).
+**"Warszawa" returns 0 results** - Warsaw uses district names (Mokotow, Wola, Srodmiescie, Bemowo, etc.). Use `list_locations(search="warsz")` to find valid names. Same applies to Krakow (use "Krakow-Podgorze", "Krakow-Srodmiescie", etc.).
 
-**401 Unauthorized (HTTP mode)** — The `Authorization` header must be `Bearer cngrm_...` (with the `Bearer` prefix). Double-check that the full API key is included, not just the prefix.
+**401 Unauthorized (HTTP mode)** - The `Authorization` header must be `Bearer cngrm_...` (with the `Bearer` prefix). Double-check that the full API key is included, not just the prefix.
 
 ## Development
 

package/dist/client-id.js

@@ -22,7 +22,7 @@ export function getClientId() {
         }
     }
     catch {
-        // File doesn't exist or isn't readable — generate new
+        // File doesn't exist or isn't readable - generate new
     }
     // Generate and persist
     const id = randomUUID();
@@ -31,7 +31,7 @@ export function getClientId() {
         writeFileSync(CLIENT_ID_FILE, id + "\n", { mode: 0o600 });
     }
     catch {
-        // Read-only fs (Docker, sandbox) — use ephemeral ID
+        // Read-only fs (Docker, sandbox) - use ephemeral ID
     }
     cachedId = id;
     return id;

package/dist/index.js

@@ -16,11 +16,11 @@ 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 - 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):",
+            "CRITICAL - District names (ALWAYS verify first):",
             "- NEVER guess district names. Call list_locations(search=\"city\") first.",
-            "- Warsaw: use district names (Mokotów, Wola, Śródmieście) — \"Warszawa\" returns 0 results",
+            "- Warsaw: use district names (Mokotów, Wola, Śródmieście) - \"Warszawa\" returns 0 results",
             "- Kraków: Kraków-Śródmieście, Kraków-Podgórze, Kraków-Krowodrza, Kraków-Nowa Huta",
             "- Most cities (Gdańsk, Gdynia, Sopot, Poznań): just the city name, no sub-districts",
             "",
@@ -29,14 +29,14 @@ export function createMcpServer(apiKey) {
             "- 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",
+            "- 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",
+            "- 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",
+            "- For §79-compliant export table or interactive map - direct user to cenogram.pl",
         ].join("\n"),
     });
     registerTools(server, apiKey);
@@ -55,10 +55,6 @@ async function main() {
                 if (pathname === "/mcp") {
                     const auth = req.headers.authorization;
                     const apiKeyFromHeader = auth?.startsWith("Bearer ") ? auth.slice(7).trim() : undefined;
-                    if (!apiKeyFromHeader) {
-                        res.writeHead(401, { "Content-Type": "application/json" }).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message: "Authorization: Bearer <api-key> required" }, id: null }));
-                        return;
-                    }
                     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
                     const mcpServer = createMcpServer(apiKeyFromHeader);
                     try {

package/dist/tools.js

@@ -11,6 +11,11 @@ function formatCreditFooter(creditInfo) {
         return "";
     return `\n---\nTokeny API: ${creditInfo.balance} pozostało (koszt zapytania: ${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");
+    }
+}
 async function withErrorHandling(fn) {
     try {
         return await fn();
@@ -27,7 +32,7 @@ export function registerTools(server, apiKey) {
 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.`, {
-        location: z.string().optional().describe("Location name — city (e.g. 'Kraków', 'Gdańsk') or district (e.g. 'Mokotów', 'Śródmieście'). For Warsaw, use district names (Mokotów, Wola, etc.) — 'Warszawa' won't match. Use list_locations to find valid names."),
+        location: z.string().optional().describe("Location name - city (e.g. 'Kraków', 'Gdańsk') or district (e.g. 'Mokotów', 'Śródmieście'). For Warsaw, use district names (Mokotów, Wola, etc.) - 'Warszawa' won't match. Use list_locations to find valid names."),
         propertyType: z.enum(["land", "building", "developed_land", "unit"]).optional()
             .describe("Property type filter"),
         marketType: z.enum(["primary", "secondary"]).optional()
@@ -38,7 +43,7 @@ Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.`, {
         dateTo: z.string().optional().describe("End date (YYYY-MM-DD)"),
         street: z.string().optional().describe("Street name filter (partial match, e.g. 'Puławska', 'Trakt Lubelski')"),
         buildingNumber: z.string().optional().describe("Building/house number (e.g. '251C', '12A'). Requires location or street to be set."),
-        parcelId: z.string().optional().describe("Exact parcel ID as returned in search results (e.g. '146518_8.0108.27'). Must match exactly — copy from a previous search result's parcel_id field."),
+        parcelId: z.string().optional().describe("Exact parcel ID as returned in search results (e.g. '146518_8.0108.27'). Must match exactly - copy from a previous search result's parcel_id field."),
         minArea: z.number().optional().describe("Minimum area in m²"),
         maxArea: z.number().optional().describe("Maximum area in m²"),
         limit: z.number().min(1).max(50).default(10)
@@ -50,6 +55,7 @@ Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.`, {
         page: z.number().min(1).default(1).optional()
             .describe("Page number for pagination (default: 1)"),
     }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+        requireApiKey(apiKey);
         const txParams = {
             district: params.location,
             propertyType: mapPropertyType(params.propertyType),
@@ -77,9 +83,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.
-For Warsaw: use district names (Mokotów, Wola) — 'Warszawa' won't match any results.`, {
+For Warsaw: use district names (Mokotów, Wola) - 'Warszawa' won't match any results.`, {
         location: z.string().optional().describe("Filter by location name (case-insensitive partial match). E.g. 'Kraków' matches 'Kraków-Podgórze', 'Kraków-Śródmieście', etc. Omit for all Poland."),
     }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+        requireApiKey(apiKey);
         const { data: allRows, creditInfo } = await getPricePerM2(apiKey);
         let rows = allRows;
         if (params.location) {
@@ -95,6 +102,7 @@ Useful for understanding the overall market price structure in Poland.`, {
         maxPrice: z.number().default(3_000_000)
             .describe("Maximum price to include (default 3,000,000 PLN)"),
     }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+        requireApiKey(apiKey);
         const { data: bins, creditInfo } = await getPriceHistogram(params.bins, params.maxPrice, apiKey);
         return textResponse(formatHistogram(bins) + formatCreditFooter(creditInfo));
     }));
@@ -119,6 +127,7 @@ Example: find apartment sales within 2km of Warsaw's Palace of Culture (lat 52.2
         limit: z.number().min(1).max(50).default(20)
             .describe("Number of results (1-50, default 20)"),
     }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+        requireApiKey(apiKey);
         const bbox = radiusKmToBbox(params.latitude, params.longitude, params.radiusKm);
         const txParams = {
             bbox: bbox.join(","),
@@ -141,17 +150,19 @@ Example: find apartment sales within 2km of Warsaw's Palace of Culture (lat 52.2
     // ── 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 () => {
+        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.
+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 () => {
+        requireApiKey(apiKey);
         const { data: allDistricts, creditInfo } = await getDistricts(apiKey);
         let districts = allDistricts;
         if (params.search) {
@@ -183,6 +194,7 @@ Example: search for parcels starting with '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 () => {
+        requireApiKey(apiKey);
         const { data, creditInfo } = await searchParcels(params.q, params.limit, apiKey);
         return textResponse(formatParcelResults(data, params.q) + formatCreditFooter(creditInfo));
     }));
@@ -212,6 +224,7 @@ Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21
         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 () => {
+        requireApiKey(apiKey);
         const { data, creditInfo } = await searchByPolygon({
             polygon: params.polygon,
             propertyType: mapPropertyType(params.propertyType),
@@ -236,7 +249,7 @@ Requires at least one filter besides districts (e.g., propertyType).
 Example: compare Mokotów, Wola, Ursynów for apartments.`, {
         districts: z.string().min(1).describe("Comma-separated district names to compare (2-5). E.g. 'Mokotów,Wola,Ursynów'"),
         propertyType: z.enum(["land", "building", "developed_land", "unit"]).optional()
-            .describe("Property type filter (recommended — API requires at least one filter)"),
+            .describe("Property type filter (recommended - API requires at least one filter)"),
         marketType: z.enum(["primary", "secondary"]).optional()
             .describe("Market type filter"),
         minPrice: z.number().optional().describe("Minimum price in PLN"),
@@ -247,6 +260,7 @@ Example: compare Mokotów, Wola, Ursynów for apartments.`, {
         maxArea: z.number().optional().describe("Maximum area in m²"),
         street: z.string().optional().describe("Street name filter"),
     }, { readOnlyHint: true }, async (params) => withErrorHandling(async () => {
+        requireApiKey(apiKey);
         const { data, creditInfo } = await compareLocations({
             districts: params.districts,
             propertyType: mapPropertyType(params.propertyType),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cenogram/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP Server for Polish real estate transaction data (7M+ transactions from RCN)",
   "type": "module",
   "bin": {