pl.cityon/mcp
by zagubiony99
README.md
# cityon-mcp
Remote MCP server for [cityon.pl](https://cityon.pl): real estate listings and local businesses in Poland.
Read-only, no login. Endpoint: `https://cityon.pl/mcp` (Streamable HTTP). Registry name: `pl.cityon/mcp`.
- About 38,000 property listings from real estate agencies across Poland (apartments, houses, plots,
commercial premises, warehouses, garages, rooms; sale and rent), new-build units from statutory developer
price lists and transaction prices from notarial deeds.
- About 954,000 businesses and places with opening hours, addresses and categories.
Add it to Claude Code: `claude mcp add --transport http cityon https://cityon.pl/mcp`
Tools: `search_properties`, `get_property`, `get_property_stats`, `list_investments`, `get_investment`,
`get_apartment_prices`, `search_businesses`, `get_business`, `list_categories`, `nearby`.
The rest of this file is in Polish.
---
Serwer MCP cityon.pl. Daje asystentom AI (Claude, ChatGPT, Perplexity, Le Chat i innym klientom MCP)
dostęp do katalogu firm i nieruchomości z cityon.pl. Tylko odczyt, bez logowania.
Nieruchomości: ok. 38 tys. ofert od biur nieruchomości z całej Polski (mieszkania, domy, działki, lokale użytkowe,
hale, garaże, pokoje; sprzedaż i wynajem), plan rozbudowy do ok. 50 tys. ofert do końca 2026 roku, do tego lokale
z ustawowych wykazów cen deweloperów i ceny transakcyjne z aktów notarialnych.
* Transport: Streamable HTTP, adres `/mcp` (bez sesji).
* Hosting: Cloudflare Workers, darmowy plan.
* Dane: publiczne API backendu `https://cityon.pl/api/public/mcp/*`.
* Ochrona: 60 zapytań na minutę z jednego IP (Cloudflare Rate Limiting), maks. 20 wyników,
brak stronicowania, pamięć podręczna odpowiedzi 5 minut. Backend ma własny wspólny limit 600/min.
## Narzędzia
| Narzędzie | Co robi |
|---|---|
| `search_businesses` | firmy po nazwie lub rodzaju, opcjonalnie w mieście i kategorii |
| `get_business` | pełne dane jednej firmy (godziny, adres, www, ocena, telefon gdy właściciel pozwala) |
| `list_categories` | kategorie z liczbą firm, w mieście albo w całej Polsce |
| `nearby` | najbliższe firmy wokół punktu, promień do 10 km |
| `search_properties` | oferty nieruchomości w mieście lub w promieniu do 50 km: mieszkania, domy, działki (z rodzajem), lokale użytkowe, hale, garaże, pokoje; sprzedaż lub wynajem; rynek pierwotny (wykazy deweloperów) i wtórny |
| `get_property` | jedna oferta lub lokal z wykazu, z historią ceny |
| `get_property_stats` | liczba ofert wg rodzaju i transakcji, w mieście albo w Polsce (z miastami o największej liczbie ofert) |
| `list_investments` | inwestycje deweloperskie w mieście |
| `get_investment` | jedna inwestycja z 10 najtańszymi lokalami |
| `get_apartment_prices` | ceny transakcyjne z aktów notarialnych (Rejestr Cen Nieruchomości) |
Każdy wynik zawiera kanoniczny link do cityon.pl (pole `url`).
Działki, lokale, hale, garaże, pokoje, wynajem, promień wokół miasta i `get_property_stats` wymagają backendu
z MR https://gitlab.com/cityon/backend/-/merge_requests/636. Na starszym backendzie narzędzie odpowiada krótkim
komunikatem, że opcja jest właśnie włączana, a mieszkania i domy na sprzedaż działają jak dotąd.
## Test lokalny
```bash
npm install
cp .dev.vars.example .dev.vars # API_BASE=http://localhost:8788 (atrapa z danymi testowymi)
npm run dev:mock # atrapa backendu na :8788, w osobnym terminalu
npm run dev # Worker na http://localhost:8787/mcp
npm test # testy automatyczne
```
Gdy backend z `/api/public/mcp/*` jest już na produkcji, w `.dev.vars` ustaw `API_BASE=https://cityon.pl`
i testuj na prawdziwych danych.
### MCP Inspector
```bash
npm run inspector
```
W przeglądarce: Transport Type `Streamable HTTP`, URL `http://localhost:8787/mcp`, Connect, zakładka Tools.
Z wiersza poleceń:
```bash
npx @modelcontextprotocol/inspector@2.9.0 --cli http://localhost:8787/mcp --transport http --method tools/list
npx @modelcontextprotocol/inspector@2.9.0 --cli http://localhost:8787/mcp --transport http \
--method tools/call --tool-name search_businesses --tool-arg query=pizzeria --tool-arg city=Kraków
```
## Wdrożenie
1. Konto Cloudflare (darmowe) i logowanie w terminalu: `npx wrangler login`.
2. `npm run deploy`. Wrangler poda adres `https://cityon-mcp.<twoja-subdomena>.workers.dev`.
3. Sekret dla nginx (dowolny losowy ciąg, min. 16 znaków): `npx wrangler secret put PROXY_SECRET`.
Ten sam ciąg wpisz w konfiguracji nginx niżej. Sekretu nie ma w repozytorium.
4. Rekord DNS w home.pl: `mcp.cityon.pl` typu A na adres naszego serwera, potem certyfikat
(np. `certbot --nginx -d mcp.cityon.pl`).
5. Nginx na naszym serwerze:
```nginx
server {
listen 443 ssl http2;
server_name mcp.cityon.pl;
# ssl_certificate ... (z certbota)
location / {
proxy_pass https://cityon-mcp.<twoja-subdomena>.workers.dev;
proxy_ssl_server_name on;
proxy_set_header Host cityon-mcp.<twoja-subdomena>.workers.dev;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Cityon-Proxy "<PROXY_SECRET>";
proxy_http_version 1.1;
proxy_buffering off; # odpowiedzi strumieniowe (SSE)
proxy_read_timeout 120s;
}
}
```
Bez `X-Cityon-Proxy` Worker widziałby adres naszego serwera zamiast adresu klienta, a limit na IP
objąłby wszystkich naraz.
Sprawdzenie: `curl https://mcp.cityon.pl/health` zwraca `{"ok": true}`.
## Podłączenie w klientach
Adres serwera: `https://mcp.cityon.pl/mcp` (przed konfiguracją nginx działa też adres workers.dev + `/mcp`).
**Claude (claude.ai i aplikacja)**
Ustawienia, Connectors, Add custom connector. Nazwa `cityon`, URL `https://mcp.cityon.pl/mcp`, bez uwierzytelniania.
Potem w rozmowie włącz konektor w menu narzędzi.
**Claude Code**
`claude mcp add --transport http cityon https://mcp.cityon.pl/mcp`
**ChatGPT (tryb deweloperski)**
Ustawienia, Apps & Connectors, Advanced settings, włącz Developer mode. Potem Create (nowy konektor):
nazwa `cityon`, MCP Server URL `https://mcp.cityon.pl/mcp`, Authentication: No authentication.
W rozmowie wybierz tryb deweloperski i konektor cityon. Tryb deweloperski jest dostępny tylko w części planów.
**Perplexity**
Ustawienia, Connectors, dodanie własnego konektora zdalnego z adresem `https://mcp.cityon.pl/mcp`,
jeśli plan na to pozwala. Dostępność tej opcji zależy od planu i wersji aplikacji, warto sprawdzić przed testem.
**Inne klienty (Le Chat, Cursor, VS Code i inne)**
Dodaj serwer MCP typu „HTTP” lub „Streamable HTTP” z adresem `https://mcp.cityon.pl/mcp`, bez uwierzytelniania.
## Zasady
* Żadnych sekretów w repozytorium: `.dev.vars` jest w `.gitignore`, sekrety tylko przez `wrangler secret`.
* W tekstach dla użytkowników (opisy narzędzi, komunikaty) bez półpauz i myślników typu em dash.
Pilnuje tego test w `test/server.test.ts`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues