teryt-mcp

v1.0.0

Published

12 hours ago

MCP server for the official Polish TERYT registry.

0High
0Medium
0Low

TERYT MCP

Serwer MCP dla oficjalnego rejestru TERYT. Udostępnia dane GUS o jednostkach terytorialnych, miejscowościach i ulicach jako narzędzia dla asystentów oraz automatyzacji.

Obsługiwane zbiory:

TERC - województwa, powiaty, gminy i typy jednostek;
SIMC - miejscowości;
ULIC - ulice;
WMRODZ - słownik rodzajów miejscowości.

Pakiet npm: teryt-mcp.

Typowe Pytania

To są najważniejsze zastosowania serwera.

Znalezienie jednostki TERYT

Prompt:

Znajdź identyfikator TERYT dla województwa dolnośląskiego.

Narzędzie: search_units

Input:

{
  "query": "dolnoslaskie",
  "limit": 5
}

Odpowiedź ma postać:

{
  "units": [
    {
      "confidence": 0.95,
      "matchedBy": "exact_normalized_name",
      "unit": {
        "id": "02",
        "name": "DOLNOŚLĄSKIE",
        "stateDate": "2026-01-01",
        "type": "województwo"
      }
    }
  ],
  "stateDate": "2026-01-01"
}

Znalezienie miejscowości

Prompt:

Znajdź miejscowości SIMC o nazwie Kraków.

Narzędzie: search_places

Input:

{
  "query": "Kraków",
  "limit": 5
}

Odpowiedź ma postać:

{
  "places": [
    {
      "confidence": 0.95,
      "matchedBy": "exact_normalized_name",
      "place": {
        "id": "0000000",
        "name": "Kraków",
        "stateDate": "2026-01-01",
        "unitId": "12-61-00-0"
      }
    }
  ],
  "stateDate": "2026-01-01"
}

Znalezienie ulicy

Prompt:

Znajdź ulice ULIC o nazwie Marszałkowska.

Narzędzie: search_streets

Input:

{
  "query": "Marszałkowska",
  "limit": 5
}

Odpowiedź ma postać:

{
  "streets": [
    {
      "confidence": 0.95,
      "matchedBy": "exact_normalized_name",
      "street": {
        "id": "0009876-00123",
        "code": "00123",
        "name": "Marszałkowska",
        "placeId": "0009876",
        "stateDate": "2026-01-01"
      }
    }
  ],
  "stateDate": "2026-01-01"
}

Rozpoznanie miejscowości i ulicy z tekstu

Prompt:

Rozpoznaj "Wieliszew Marszalkowska" i zwróć identyfikatory TERC, SIMC i ULIC.

Narzędzie: resolve_address

Input:

{
  "query": "Wieliszew Marszalkowska",
  "limit": 5
}

Odpowiedź ma postać:

{
  "addresses": [
    {
      "confidence": 0.95,
      "matchedBy": "exact_normalized_address",
      "address": {
        "id": "0008639-12400",
        "unit": {
          "id": "14-08-05-2",
          "name": "Wieliszew",
          "type": "gmina wiejska"
        },
        "place": {
          "id": "0008639",
          "name": "Wieliszew"
        },
        "street": {
          "id": "0008639-12400",
          "code": "12400",
          "name": "Marszałkowska"
        },
        "stateDate": "2026-06-19"
      }
    }
  ],
  "stateDate": "2026-06-19"
}

To nie jest geokodowanie. Narzędzie rozpoznaje identyfikatory rejestrowe do poziomu miejscowości i ulicy. Dla zapytań zawierających wyłącznie miejscowość użyj search_places. Kody pocztowe i numery budynków są odrzucane z czytelnym błędem, ponieważ nie należą do TERYT.

Sprawdzenie konkretnego identyfikatora

Prompt:

Sprawdź jednostkę TERYT 02-01-01-1.

Narzędzie: get_unit

Input:

{
  "id": "02-01-01-1"
}

Odpowiedź ma postać:

{
  "unit": {
    "id": "02-01-01-1",
    "name": "Bolesławiec",
    "stateDate": "2026-01-01",
    "type": "gmina miejska"
  },
  "stateDate": "2026-01-01"
}

Dla brakującego identyfikatora odpowiedź ma postać:

{
  "unit": null,
  "stateDate": null
}

Analogicznie:

get_place sprawdza identyfikator SIMC miejscowości;
get_street sprawdza identyfikator ULIC ulicy.

Co Jest W TERYT, A Czego Nie Ma

Ten serwer celowo trzyma się TERYT. Dlatego obsługuje identyfikatory i nazwy administracyjne, ale nie udaje geokodera ani rejestru adresów punktowych.

W zakresie TERYT:

województwa, powiaty, gminy i ich typy;
miejscowości i ich identyfikatory SIMC;
ulice i ich identyfikatory ULIC;
powiązania miejscowość-jednostka oraz ulica-miejscowość;
daty stanu danych z lokalnej migawki.

Poza zakresem TERYT:

współrzędne;
działki;
budynki;
kody pocztowe;
walidacja punktu adresowego, np. czy istnieje numer budynku przy ulicy.

Do tych danych potrzebne są inne źródła, np. PRG/EMUiA/GUGiK dla punktów adresowych i współrzędnych, EGiB dla katastru albo osobny słownik PNA dla kodów pocztowych. Jeśli te funkcje będą potrzebne, powinny powstać jako osobny serwer lub osobny bounded context, nie jako ukryty dodatek do TERYT.

Narzędzia MCP

Wszystkie narzędzia zwracają structuredContent.

`about`

Zwraca informacje o pakiecie, autorze, kontakcie, repozytorium, wersji serwera oraz stanie lokalnej synchronizacji danych.

Input:

{}

Odpowiedź ma postać:

{
  "author": {
    "name": "Maciej Ciemborowicz"
  },
  "contact": {
    "email": "[email protected]"
  },
  "repository": {
    "url": "https://github.com/ciembor/teryt-mcp"
  },
  "server": {
    "name": "teryt-mcp",
    "version": "0.1.13"
  },
  "data": {
    "status": "available",
    "synchronizedSuccessfully": true,
    "lastSynchronizedAt": "2026-06-21T00:00:00.000Z",
    "datasets": [
      {
        "dataset": "TERC",
        "stateDate": "2026-01-01",
        "version": "2026-01-01"
      }
    ]
  }
}

TERYT nie ma tu klasycznej wersji semver danych. Pole version jest datą stanu danych STAN_NA z lokalnego manifestu synchronizacji.

`health_status`

Sprawdza, czy serwer odpowiada.

Input:

{}

Odpowiedź:

{
  "ok": true
}

`server_status`

Zwraca status runtime serwera.

Input:

{}

Odpowiedź ma postać:

{
  "serverName": "teryt-mcp",
  "serverVersion": "0.1.13",
  "frameworkVersion": "0.2.1",
  "transport": "stdio",
  "dataDir": "/path/to/teryt-data",
  "database": {
    "status": "available"
  }
}

`source_status`

Pokazuje status lokalnej bazy i metadane źródeł TERYT.

Input:

{}

Odpowiedź ma postać:

{
  "datasets": [
    {
      "dataset": {
        "code": "TERC",
        "name": "Territorial units",
        "sourceUrl": "https://eteryt.stat.gov.pl/eTeryt/"
      },
      "snapshot": null,
      "stateDate": null,
      "sha256": null
    }
  ],
  "lastCheckedAt": null,
  "lastSuccessfulSync": null,
  "localDatabase": {
    "status": "missing"
  },
  "remoteSource": {
    "status": "unknown",
    "errors": []
  }
}

`sync_database`

Buduje albo przebudowuje lokalną bazę SQLite z oficjalnych danych TERYT.

Input:

{
  "mode": "missing"
}

Tryby:

missing  zbuduj bazę tylko wtedy, gdy jej brakuje
stale    przebuduj bazę, jeśli ma co najmniej 24 godziny
force    przebuduj bazę pod lockiem

Jeśli baza już istnieje, a tryb to missing, odpowiedź ma postać:

{
  "status": "skipped",
  "mode": "missing",
  "databasePath": null,
  "datasets": []
}

Po przebudowie odpowiedź ma postać:

{
  "status": "synced",
  "mode": "force",
  "databasePath": "/path/to/teryt.sqlite",
  "datasets": [
    {
      "dataset": "TERC",
      "recordCount": 123456,
      "stateDate": "2026-01-01",
      "source": "official-teryt-download",
      "sourceUrl": "https://eteryt.stat.gov.pl/eTeryt/",
      "variant": "full"
    }
  ]
}

`search_units`

Szuka jednostek TERC.

Input:

{
  "query": "Boleslawiec",
  "limit": 20
}

Zwraca:

{
  "units": [],
  "stateDate": "2026-01-01"
}

`search_places`

Szuka miejscowości SIMC.

Input:

{
  "query": "Stara Wieś",
  "limit": 20
}

Zwraca:

{
  "places": [],
  "stateDate": "2026-01-01"
}

`search_streets`

Szuka ulic ULIC.

Input:

{
  "query": "Marszałkowska",
  "limit": 20
}

Zwraca:

{
  "streets": [],
  "stateDate": "2026-01-01"
}

`resolve_address`

Szuka kandydata adresowego do poziomu miejscowości i ulicy.

Input:

{
  "place": "Bolesławiec",
  "street": "Marszałkowska",
  "limit": 20
}

Można również przekazać query, np. Marszalkowska Boleslawiec albo ulica Marszalkowska w Boleslawiec. Pola place i street są preferowane, gdy klient potrafi rozdzielić miejscowość od ulicy.

Zwraca:

{
  "addresses": [],
  "stateDate": "2026-01-01"
}

`get_unit`

Pobiera jednostkę TERC po identyfikatorze.

Input:

{
  "id": "02-01-01-1"
}

`get_place`

Pobiera miejscowość SIMC po identyfikatorze.

Input:

{
  "id": "0009876"
}

`get_street`

Pobiera ulicę ULIC po identyfikatorze.

Input:

{
  "id": "0009876-00123"
}

Dopasowanie I Ranking

matchedBy mówi, dlaczego wynik został zwrócony:

exact_code
exact_normalized_name
exact_normalized_address
prefix
contains

confidence jest wynikiem rankingu wyszukiwania, a nie oficjalną wartością z rejestru. Dopasowanie po dokładnym kodzie ma najwyższy priorytet. Dopasowania zawierające szukany fragment są niżej.

Wyszukiwanie normalizuje polskie znaki, więc zapytania takie jak Boleslawiec mogą znaleźć Bolesławiec.

Instalacja

Uruchomienie bez instalacji globalnej:

npx -y teryt-mcp serve

Instalacja globalna:

npm install -g teryt-mcp
teryt-mcp serve

Wymagania:

Node.js >=20.19.0

Podczas instalacji pakiet próbuje utworzyć lokalną bazę SQLite z oficjalnych danych TERYT. Jeśli pierwsza synchronizacja się nie powiedzie, instalacja nadal kończy się sukcesem. Bazę można zsynchronizować później przez CLI albo narzędzie sync_database.

Pominięcie synchronizacji podczas instalacji:

TERYT_MCP_SKIP_POSTINSTALL_SYNC=1 npm install -g teryt-mcp

Podłączenie Do Klienta MCP

Konfiguracja dla transportu stdio:

{
  "mcpServers": {
    "teryt": {
      "command": "npx",
      "args": ["-y", "teryt-mcp", "serve"]
    }
  }
}

Przy instalacji globalnej:

{
  "mcpServers": {
    "teryt": {
      "command": "teryt-mcp",
      "args": ["serve"]
    }
  }
}

W środowisku, które czyści cache między uruchomieniami, ustaw stały katalog danych:

{
  "mcpServers": {
    "teryt": {
      "command": "npx",
      "args": ["-y", "teryt-mcp", "serve"],
      "env": {
        "MCP_DATA_DIR": "/absolute/path/to/teryt-data"
      }
    }
  }
}

Codex

Codex CLI i rozszerzenie Codex dla IDE współdzielą konfigurację ~/.codex/config.toml. Plik VS Code User/mcp.json nie rejestruje serwera w Codex.

Najprościej dodać globalnie zainstalowany serwer poleceniem:

codex mcp add teryt-mcp -- teryt-mcp serve

Odpowiednik w ~/.codex/config.toml:

[mcp_servers.teryt-mcp]
command = "teryt-mcp"
args = ["serve"]

Po zmianie konfiguracji uruchom nowy proces lub nową sesję Codex i sprawdź serwer przez codex mcp list albo /mcp w interfejsie terminalowym.

Pierwsza Synchronizacja

Serwer może zwracać status bez lokalnej bazy, ale wyszukiwanie i lookupy wymagają bazy SQLite.

Podstawowe komendy CLI:

teryt-mcp help
teryt-mcp about
teryt-mcp status
teryt-mcp source-status

Wymuszenie synchronizacji:

npx -y teryt-mcp sync --force

Albo, przy instalacji globalnej:

teryt-mcp sync --force

Synchronizacja zapisuje bazę atomowo. Proces czytający powinien zobaczyć albo starą bazę, albo nową, nigdy częściowo zapisany plik.

CLI

CLI jest pomocnicze. Pełny zestaw funkcji jest dostępny przez MCP.

teryt-mcp serve
teryt-mcp status
teryt-mcp source-status
teryt-mcp sync
teryt-mcp sync --force
teryt-mcp sync --mode missing
teryt-mcp search places Kraków --limit 5

Obecnie CLI obsługuje wyszukiwanie tylko dla search places. Narzędzia MCP udostępniają również jednostki, ulice, rozpoznawanie adresu i lookupy po identyfikatorach.

Przykład:

teryt-mcp search places Boleslawiec --limit 1

Odpowiedź ma postać:

{
  "places": [
    {
      "confidence": 0.95,
      "matchedBy": "exact_normalized_name",
      "place": {
        "id": "0009876",
        "name": "Bolesławiec",
        "stateDate": "2026-01-01",
        "unitId": "02-01-01-1"
      }
    }
  ],
  "stateDate": "2026-01-01"
}

HTTP

HTTP jest przydatne do lokalnego testowania albo własnych wrapperów:

MCP_TRANSPORT=http PORT=3000 teryt-mcp serve

Endpointy:

GET  /health
POST /tools/:toolName

Przykład:

curl -s http://127.0.0.1:3000/tools/search_places \
  -H 'content-type: application/json' \
  -d '{"query":"Kraków","limit":3}'

Odpowiedź HTTP zawiera wynik narzędzia MCP:

{
  "structuredContent": {
    "places": [
      {
        "confidence": 0.95,
        "matchedBy": "exact_normalized_name",
        "place": {
          "id": "0000000",
          "name": "Kraków",
          "stateDate": "2026-01-01",
          "unitId": "12-61-00-0"
        }
      }
    ],
    "stateDate": "2026-01-01"
  }
}

Konfiguracja Runtime

MCP_TRANSPORT=stdio|http  # domyślnie stdio
MCP_PORT / PORT           # domyślnie 3000 dla HTTP
MCP_DATA_DIR              # katalog bazy i manifestu synchronizacji
XDG_CACHE_HOME            # używane, gdy MCP_DATA_DIR nie jest ustawione
MCP_LOG_LEVEL             # debug|info|warn|error|silent

Pliki lokalne:

<data-dir>/teryt.sqlite
<data-dir>/sync-manifest.json
<data-dir>/*.lock

Nowe wydania mogą zmieniać schemat SQLite. Serwer wykrywa niezgodną bazę i przebudowuje ją podczas synchronizacji w trybie missing; można też jawnie uruchomić teryt-mcp sync --force.

Development

Dla osób rozwijających repozytorium:

pnpm install
pnpm build
pnpm quality

Szczegóły architektury i kontraktów:

Licencja i źródło danych

Dane TERYT pochodzą z Głównego Urzędu Statystycznego. Informacje o ich pozyskiwaniu i przetwarzaniu znajdują się w pliku NOTICE.md.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TERYT MCP

Typowe Pytania

Znalezienie jednostki TERYT

Znalezienie miejscowości

Znalezienie ulicy

Rozpoznanie miejscowości i ulicy z tekstu

Sprawdzenie konkretnego identyfikatora

Co Jest W TERYT, A Czego Nie Ma

Narzędzia MCP

about

health_status

server_status

source_status

sync_database

search_units

search_places

search_streets

resolve_address

get_unit

get_place

get_street

Dopasowanie I Ranking

Instalacja

Podłączenie Do Klienta MCP

Codex

Pierwsza Synchronizacja

CLI

HTTP

Konfiguracja Runtime

Development

Licencja i źródło danych

`about`

`health_status`

`server_status`

`source_status`

`sync_database`

`search_units`

`search_places`

`search_streets`

`resolve_address`

`get_unit`

`get_place`

`get_street`