@teryt24/mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @teryt24/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Model Context Protocol](https://modelcontextprotocol.io) stdio server
+for the [teryt24.pl API](https://teryt24.pl/docs) — twelve tools that let
+an agent search Polish localities, streets and postal codes, validate and
+geocode addresses, and read the TERYT change feed.
+
+- **Runs in the client's process.** stdio transport; the API key comes
+  from an environment variable and never leaves the machine.
+- **Results pass through verbatim.** A tool returns the API's own JSON —
+  no re-shaping — so the API's documentation applies unchanged, including
+  the `{error, message, code, details}` error envelope.
+- **Built on `@teryt24/api`.** The tools call the official client, so the
+  SDK and the server move together.
+
+## Install & register
+
+```bash
+npm install -g @teryt24/mcp        # or just use npx, below
+```
+
+Point your MCP host at it (Claude-style config; the same shape works for
+other hosts):
+
+```json
+{
+  "mcpServers": {
+    "teryt24": {
+      "command": "npx",
+      "args": ["-y", "@teryt24/mcp"],
+      "env": { "TERYT24_API_KEY": "t24_..." }
+    }
+  }
+}
+```
+
+Environment:
+
+| Variable | Meaning |
+|---|---|
+| `TERYT24_API_KEY` | Optional. The key sent as `X-API-Key`; keyless calls share a 60 req/min/IP bucket. |
+| `TERYT24_API_BASE` | Optional. The API base URL (default `https://teryt24.pl`) — for self-hosted instances. |
+
+## The tools
+
+| Tool | Answers |
+|---|---|
+| `search_localities` | Which places match a name (or lie near a coordinate) — GUS SIMC, ≈54k entries. |
+| `search_streets` | Streets by name — within one locality, or country-wide. |
+| `search_postal_codes` | Postal codes by prefix, by locality, or nearest to a coordinate. |
+| `validate_address` | A written address → structured fields, per-field match kinds, a verdict and the issues. |
+| `geocode` | An address → building coordinates at house-number precision (GUGiK PRG). |
+| `reverse_geocode` | A coordinate → the nearest address. |
+| `get_locality` | One locality's full record (hierarchy, postal codes, street count, figures). |
+| `get_street` | One street's full record (every locality it is registered in, PRG aggregates). |
+| `get_postal_code` | One postal code's full record (localities served, PRG aggregates). |
+| `list_regions` | The TERC hierarchy: 16 voivodeships, or one voivodeship's counties/municipalities. |
+| `get_region_stats` | A unit's statistics: the demographic decomposition (voivodeship) or the 2021 census. |
+| `list_changes` | What the official registers changed, and when (the TERYT change feed). |
+
+Input arguments use the same names as the API's query parameters —
+[`/docs`](https://teryt24.pl/docs) documents every one of them, including
+the search semantics (diacritics-insensitive matching, disambiguation by
+TERC codes, the `offset` ≤ 10 000 paging bound).
+
+## Attribution
+
+When results are displayed to users, attribute the data — `Data: GUS
+TERYT, PRG address points (GUGiK), GeoNames postal codes — via
+teryt24.pl` — per the [usage policy](https://teryt24.pl/usage-policy).

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * The stdio MCP server entry point (`@teryt24/mcp`).
+ *
+ * Runs IN THE CLIENT'S PROCESS (an editor, an agent host, a CI job): it
+ * reads the API key from the environment and talks to teryt24.pl over
+ * HTTPS through the `@teryt24/api` client. The key never leaves the
+ * customer's machine, and the API service gains no new attack surface —
+ * the server is just another HTTPS client of /v1.
+ *
+ * Environment:
+ *   TERYT24_API_KEY   the API key sent as X-API-Key (optional; keyless
+ *                     calls share the 60 req/min/IP bucket)
+ *   TERYT24_API_BASE  an API base URL override (default
+ *                     https://teryt24.pl — for self-hosted instances)
+ *
+ * Register with an MCP host, e.g. a Claude-style config:
+ *
+ *   { "mcpServers": { "teryt24": {
+ *       "command": "npx", "args": ["-y", "@teryt24/mcp"],
+ *       "env": { "TERYT24_API_KEY": "t24_..." } } } }
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Teryt24Api } from "@teryt24/api";
+/**
+ * Builds the server around a client. Exported for the test suite (the
+ * InMemory transport wires a test client to it without spawning a
+ * process) — the stdio entry point below is the only thing `bin` runs.
+ */
+export declare function buildMcpServer(client: Teryt24Api): McpServer;

package/dist/index.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * The stdio MCP server entry point (`@teryt24/mcp`).
+ *
+ * Runs IN THE CLIENT'S PROCESS (an editor, an agent host, a CI job): it
+ * reads the API key from the environment and talks to teryt24.pl over
+ * HTTPS through the `@teryt24/api` client. The key never leaves the
+ * customer's machine, and the API service gains no new attack surface —
+ * the server is just another HTTPS client of /v1.
+ *
+ * Environment:
+ *   TERYT24_API_KEY   the API key sent as X-API-Key (optional; keyless
+ *                     calls share the 60 req/min/IP bucket)
+ *   TERYT24_API_BASE  an API base URL override (default
+ *                     https://teryt24.pl — for self-hosted instances)
+ *
+ * Register with an MCP host, e.g. a Claude-style config:
+ *
+ *   { "mcpServers": { "teryt24": {
+ *       "command": "npx", "args": ["-y", "@teryt24/mcp"],
+ *       "env": { "TERYT24_API_KEY": "t24_..." } } } }
+ */
+import { pathToFileURL } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Teryt24Api, SDK_VERSION } from "@teryt24/api";
+import { toolDefinitions } from "./tools.js";
+/** The tool result: the API's JSON, verbatim, as the one text content. */
+function jsonResult(body) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+    };
+}
+/**
+ * Builds the server around a client. Exported for the test suite (the
+ * InMemory transport wires a test client to it without spawning a
+ * process) — the stdio entry point below is the only thing `bin` runs.
+ */
+export function buildMcpServer(client) {
+    const server = new McpServer({ name: "teryt24", version: SDK_VERSION }, {
+        instructions: "Polish registry & geo data (GUS TERYT, GUGiK PRG, GeoNames postal): " +
+            "localities, streets, postal codes, address validation and geocoding. " +
+            "Start from search_localities / search_streets / search_postal_codes; " +
+            "validate_address answers a written address with a verdict and the " +
+            "issues to fix. Tool results are the API's own JSON, unchanged — the " +
+            "`code`/`message`/`details` fields of an error are the published " +
+            "error contract, and null means 'unknown', never zero.",
+    });
+    for (const tool of toolDefinitions()) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, async (args) => {
+            try {
+                const body = await tool.call(client, args ?? {});
+                return jsonResult(body);
+            }
+            catch (error) {
+                // An API error is DATA here: the verbatim error envelope
+                // ({error, message, code, details}) tells the agent which
+                // branch to take — retry a 503, fix the arguments on a 400.
+                // Inventing a prose wrapper would only blur it.
+                const isApiError = error instanceof Error && error.name === "Teryt24ApiError";
+                if (isApiError) {
+                    const apiError = error;
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(apiError.body ?? { message: error.message }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                throw error;
+            }
+        });
+    }
+    return server;
+}
+async function main() {
+    const apiKey = process.env.TERYT24_API_KEY;
+    const baseUrl = process.env.TERYT24_API_BASE;
+    const client = new Teryt24Api({
+        ...(apiKey ? { apiKey } : {}),
+        ...(baseUrl ? { baseUrl } : {}),
+    });
+    const server = buildMcpServer(client);
+    await server.connect(new StdioServerTransport());
+    // stdio serves one session for the life of the process; nothing to
+    // await after the transport is wired.
+}
+// Only the executable entry point serves stdio; the import for tests
+// must not open a transport.
+const invokedDirectly = process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    await main();
+}

package/dist/tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The MCP server for the teryt24.pl API (`@teryt24/mcp`) — twelve tools,
+ * one per surface an integration question touches, all riding the
+ * `@teryt24/api` client so the shapes are shared by construction.
+ *
+ * Two rules the plan holds this server to:
+ *
+ * - **Result JSON passes through VERBATIM.** A tool returns the API's own
+ *   response body, stringified — no re-shaping, no field renaming, no
+ *   invented summary fields. An agent reading a tool result reads exactly
+ *   what `GET /v1/...` answers, so the API's documentation (and the
+ *   `code`/`details` error contract) applies to tool output unchanged.
+ * - **It runs in the client's process.** stdio transport, the key from an
+ *   environment variable — the key never leaves the customer's machine,
+ *   and the API service gains no attack surface.
+ *
+ * The input schemas mirror the HTTP query parameters by NAME (a tool
+ * argument is the same word the API documents), so an agent can move
+ * between the /docs reference and the tools without a translation layer.
+ * The one ergonomic fold: `list_regions` takes an optional `code`, so the
+ * regions family's three list operations (the 16 voivodeships, one
+ * voivodeship's counties, one county's municipalities) ride one tool —
+ * the description spells the mapping out, and the responses are as
+ * verbatim as every other tool's.
+ */
+import { z } from "zod";
+import type { Teryt24Api } from "@teryt24/api";
+export interface McpToolDefinition {
+    name: string;
+    /** One line for a picker; the description carries the guidance. */
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType>;
+    call: (client: Teryt24Api, args: Record<string, unknown>) => Promise<unknown>;
+}
+/** The twelve tools. Order is the /docs reference family order. */
+export declare function toolDefinitions(): McpToolDefinition[];

package/dist/tools.js

@@ -0,0 +1,252 @@
+/**
+ * The MCP server for the teryt24.pl API (`@teryt24/mcp`) — twelve tools,
+ * one per surface an integration question touches, all riding the
+ * `@teryt24/api` client so the shapes are shared by construction.
+ *
+ * Two rules the plan holds this server to:
+ *
+ * - **Result JSON passes through VERBATIM.** A tool returns the API's own
+ *   response body, stringified — no re-shaping, no field renaming, no
+ *   invented summary fields. An agent reading a tool result reads exactly
+ *   what `GET /v1/...` answers, so the API's documentation (and the
+ *   `code`/`details` error contract) applies to tool output unchanged.
+ * - **It runs in the client's process.** stdio transport, the key from an
+ *   environment variable — the key never leaves the customer's machine,
+ *   and the API service gains no attack surface.
+ *
+ * The input schemas mirror the HTTP query parameters by NAME (a tool
+ * argument is the same word the API documents), so an agent can move
+ * between the /docs reference and the tools without a translation layer.
+ * The one ergonomic fold: `list_regions` takes an optional `code`, so the
+ * regions family's three list operations (the 16 voivodeships, one
+ * voivodeship's counties, one county's municipalities) ride one tool —
+ * the description spells the mapping out, and the responses are as
+ * verbatim as every other tool's.
+ */
+import { z } from "zod";
+/** Coerce-free integer: the API's limit/offset bounds, restated. */
+const limitField = (max, def) => z.number().int().min(1).max(max).optional().describe(`Maximum results (1–${max}, default ${def}).`);
+const offsetField = z
+    .number()
+    .int()
+    .min(0)
+    .max(10_000)
+    .optional()
+    .describe("Skip the first N results (0-based, max 10000) to page past the limit.");
+const tercDetail = "TERC code, the length naming the level: 2 digits for a voivodeship ('14'), 4 for a county ('1401'), 6 for a municipality ('140101').";
+/** The twelve tools. Order is the /docs reference family order. */
+export function toolDefinitions() {
+    return [
+        {
+            name: "search_localities",
+            title: "Search Polish localities",
+            description: "Search Poland's localities — cities, towns, villages (the GUS SIMC register, ≈54k entries). " +
+                "Answers the questions 'which voivodeship/county is X in', 'how many places are named X', 'what is near these coordinates'. " +
+                "Same-named localities are all returned; disambiguate by province/county (TERC codes, e.g. province '14' = Mazowieckie) or by population. " +
+                "Geographic mode (lat+lon): nearest-first with distanceKm. Rows carry the SYM id used by get_locality, geocode and validate_address.",
+            inputSchema: {
+                q: z.string().optional().describe("Name query; diacritics- and punctuation-insensitive ('wroclaw' finds 'Wrocław'). Optional in geographic mode or with a province/county/municipality/population filter."),
+                province: z.string().optional().describe("Optional 2-digit TERC voivodeship code filter (e.g. '14')."),
+                county: z.string().optional().describe("Optional 4-digit TERC code filter (WOJ+POW, e.g. '1465')."),
+                municipality: z.string().optional().describe("Optional 6-digit TERC code filter (WOJ+POW+GMI, e.g. '146503')."),
+                kind: z.enum(["urban"]).optional().describe("'urban' selects the urban units (miasto + Warszawa's dzielnica + delegatury) — the reliable 'cities' filter."),
+                rm: z.string().optional().describe("Optional rodzaj filter: a 2-digit RM code ('01' wieś, '96' miasto) or a comma-separated list ('96,95,98')."),
+                minPopulation: z.number().int().optional().describe("Optional inhabitants lower bound (unknown population is excluded)."),
+                maxPopulation: z.number().int().optional().describe("Optional inhabitants upper bound (unknown population is excluded)."),
+                lat: z.number().min(-90).max(90).optional().describe("WGS84 latitude; with lon triggers geographic (nearest-first) mode."),
+                lon: z.number().min(-180).max(180).optional().describe("WGS84 longitude; must be given together with lat."),
+                radiusKm: z.number().min(0).max(100).optional().describe("Geographic-mode radius in kilometres (default 10, max 100)."),
+                aliases: z.boolean().optional().describe("Opt-in exonym fallback: 'Danzig' finds Gdańsk when the name search came up empty."),
+                mode: z.enum(["autocomplete", "resolve", "hybrid"]).optional().describe("autocomplete = prefix-first, resolve = exact only, hybrid = combined. Ignored in geographic mode."),
+                limit: limitField(50, 10),
+                offset: offsetField,
+            },
+            call: (client, args) => client.searchLocalities(validated(normalizeArgs(args))),
+        },
+        {
+            name: "search_streets",
+            title: "Search Polish streets",
+            description: "Search streets (the GUS ULIC register, ≈310k). Within one locality (city = a SYM from search_localities): the street list of that locality. " +
+                "Without city: country-wide — 'which localities have a street with this name?' — rows then carry the locality and inflated province/county so repeated names disambiguate. " +
+                "Diacritics-insensitive; matches the name without its 'ul.'/'al.' prefix.",
+            inputSchema: {
+                city: z.string().optional().describe("Locality SYM (7 digits, from search_localities). Omit (with q) for a country-wide search."),
+                q: z.string().optional().describe("Street-name prefix ('rynek' finds 'ul. Rynek'). Required for a country-wide search; optional within a city."),
+                sort: z.enum(["name", "prominence"]).optional().describe("'prominence' ranks by real-world volume (PRG address points first) instead of the name key."),
+                limit: limitField(50, 10),
+                offset: offsetField,
+            },
+            call: (client, args) => client.searchStreets(validated(normalizeArgs(args))),
+        },
+        {
+            name: "search_postal_codes",
+            title: "Search Polish postal codes",
+            description: "Search Polish postal codes (PNA). Three modes, exactly one of: `q` (a code prefix: '59-7', '59700'), `locality` (a SYM: the codes officially serving one locality), or `lat`+`lon` (nearest codes by PRG centroid, with distanceKm). " +
+                "Rows carry the TERC-inflated hierarchy (province/county/municipality) and — when the row resolves to one locality — its SYM, type and population.",
+            inputSchema: {
+                q: z.string().optional().describe("Postal-code prefix in any form: '00-950', '00950', '00-9', '009'."),
+                locality: z.string().optional().describe("Locality SYM (7 digits): the codes serving it, one row per code."),
+                lat: z.number().min(-90).max(90).optional().describe("WGS84 latitude; with lon triggers nearest mode."),
+                lon: z.number().min(-180).max(180).optional().describe("WGS84 longitude; must be given together with lat."),
+                limit: limitField(50, 10),
+                offset: offsetField,
+            },
+            call: (client, args) => client.searchPostalCodes(validated(normalizeArgs(args))),
+        },
+        {
+            name: "validate_address",
+            title: "Validate a Polish address",
+            description: "Validate a Polish address against the official registers and get a structured answer: the corrected address fields (locality, street, house number, unit, postal code, coordinates) with registry identifiers (SYM, SYM_UL, TERC), " +
+                "a per-field match kind (exact / normalized / partial / ambiguous / not-found), a VERDICT (valid / corrected / ambiguous / incomplete / invalid) and the issues explaining every discrepancy. " +
+                "Accept three input forms: `address` (one free-text string), or `sym`/`locality` + `street`/`streetName` + `number`. The verdicts come from the same pipeline geocode uses, so the two never disagree. " +
+                "A fuzzy-tier hit is never reported as confirmed, and a value the register did not confirm is EMPTY — never a plausible guess.",
+            inputSchema: {
+                address: z.string().optional().describe("Free-text Polish address ('Wrocław, ul. Eugeniusza Horbaczewskiego 35'), parsed into locality/street/number. Mutually exclusive with the fielded form."),
+                sym: z.string().optional().describe("Locality SYM (7 digits, from search_localities) for the fielded form. Mutually exclusive with locality and address."),
+                locality: z.string().optional().describe("Locality NAME (diacritics-insensitive) for the structured-by-name form. Several matches → verdict 'ambiguous' with a candidate shortlist."),
+                postalCode: z.string().optional().describe("The caller's claim about the postal code — VERIFIED against the matched building point's own code; a disagreement is reported as the postal_code_mismatch issue."),
+                number: z.string().optional().describe("House number ('21A'). Optional here: a missing number makes the address INCOMPLETE, not invalid."),
+                street: z.string().optional().describe("Street SYM_UL (5 digits, from search_streets). Mutually exclusive with streetName."),
+                streetName: z.string().optional().describe("Street-name prefix ('rynek' finds 'ul. Rynek'). Several matches → verdict 'ambiguous' with candidates."),
+                limit: limitField(50, 10),
+            },
+            call: (client, args) => client.validate(validated(normalizeArgs(args))),
+        },
+        {
+            name: "geocode",
+            title: "Geocode a Polish address",
+            description: "Resolve a Polish address to building coordinates (WGS84) at house-number precision, from the GUGiK PRG address points (~8.6M rows). " +
+                "Same three input forms as validate_address (free-text `address`, `sym`+street, or `locality` name); several matches of a street/locality name answer 'ambiguous' with candidates rather than picking one. " +
+                "Use validate_address when you need the verdict and the issues; use geocode when you need the point.",
+            inputSchema: {
+                address: z.string().optional().describe("Free-text Polish address; parsed into locality/street/number internally."),
+                sym: z.string().optional().describe("Locality SYM (7 digits). Required unless address or locality is given."),
+                locality: z.string().optional().describe("Locality NAME instead of a SYM — resolved through the locality index; several matches → result 'locality-ambiguous' with a shortlist."),
+                postalCode: z.string().optional().describe("Optional narrowing hint for the locality mode: only localities the code officially serving stay candidates."),
+                number: z.string().optional().describe("House number ('21A'). Required unless address is given."),
+                street: z.string().optional().describe("Street SYM_UL (5 digits). Omit for rural 'locality + number' addresses."),
+                streetName: z.string().optional().describe("Street-name prefix. Several matches → result 'street-ambiguous' with candidates."),
+                limit: limitField(50, 10),
+            },
+            call: (client, args) => client.geocode(validated(normalizeArgs(args))),
+        },
+        {
+            name: "reverse_geocode",
+            title: "Reverse-geocode a coordinate",
+            description: "Given a WGS84 coordinate, return the nearest Polish address(es) — the PRG address points within 128 km, distance-sorted with distanceKm, each with street, locality, house number and postal code. " +
+                "Where no address is near enough, the nearest localities from the registry are offered (result 'locality') instead of a wrong pin.",
+            inputSchema: {
+                lat: z.number().min(-90).max(90).describe("WGS84 latitude."),
+                lon: z.number().min(-180).max(180).describe("WGS84 longitude."),
+                limit: limitField(50, 5),
+            },
+            call: (client, args) => client.reverseGeocode(validated(normalizeArgs(args))),
+        },
+        {
+            name: "get_locality",
+            title: "Get one locality",
+            description: "Full record of one Polish locality by SYM: identity and administrative hierarchy (province → county → municipality, TERC codes and names), the postal codes serving it, its registered street count, " +
+                "and — where published — its population figures and 2021 census blocks. Use search_localities first when you have a name, not an id.",
+            inputSchema: {
+                sym: z.string().describe("Locality SYM (7 digits, from search_localities)."),
+            },
+            call: (client, args) => client.locality(requireString(args, "sym")),
+        },
+        {
+            name: "get_street",
+            title: "Get one street",
+            description: "Full record of one street by SYM_UL: the display name and type (cecha), every locality where that street id is registered (with hierarchy and coordinates), and the PRG aggregates (address points, postal codes, centroid, house numbers) per occurrence.",
+            inputSchema: {
+                symUl: z.string().describe("Street SYM_UL (5 digits, from search_streets rows' id)."),
+            },
+            call: (client, args) => client.street(requireString(args, "symUl")),
+        },
+        {
+            name: "get_postal_code",
+            title: "Get one postal code",
+            description: "Full record of one Polish postal code: every locality the code serves (TERC-inflated), plus the official PRG aggregates — building count, distinct streets, weighted centroid, and a street-name sample. " +
+                "Accepts the display ('59-700') or digits ('59700') form.",
+            inputSchema: {
+                code: z.string().describe("Postal code, '59-700' or '59700'."),
+            },
+            call: (client, args) => client.postalCode(requireString(args, "code")),
+        },
+        {
+            name: "list_regions",
+            title: "List regions (TERC hierarchy)",
+            description: "The administrative hierarchy from the TERC register. With NO arguments: the 16 voivodeships. With `code` (a 2-digit voivodeship TERC, e.g. '14'): that voivodeship's counties (miasta na prawach powiatu included; pass kind='municipalities' for its municipalities, optionally narrowed with `county`). " +
+                "Rows carry the verbatim TERC names and codes the other tools' province/county/municipality filters take.",
+            inputSchema: {
+                code: z.string().optional().describe("Optional 2-digit voivodeship TERC (e.g. '14'): lists that voivodeship's counties instead of all voivodeships."),
+                kind: z.enum(["counties", "municipalities"]).optional().describe("With code: 'counties' (default) or 'municipalities' (gminy)."),
+                county: z.string().optional().describe("With code and kind='municipalities': optional 2-digit county code to narrow to one county."),
+            },
+            call: async (client, args) => {
+                const code = typeof args.code === "string" ? args.code : undefined;
+                if (code === undefined) {
+                    return client.regions();
+                }
+                if (args.kind === "municipalities") {
+                    const county = typeof args.county === "string" ? args.county : undefined;
+                    return client.regionMunicipalities(code, county ? { county } : {});
+                }
+                return client.regionCounties(code);
+            },
+        },
+        {
+            name: "get_region_stats",
+            title: "Get region statistics",
+            description: "Statistics for one administrative unit by TERC code. `kind` selects the measurement: 'demography' (default) = the voivodeship's demographic decomposition — natural balance (births − deaths), net internal and net foreign migration per year, reconciled against the population series, with the residual returned as it stands; 'census' = the NSP 2021 census blocks (economic activity, dwellings, buildings, households) for a voivodeship (2-digit code, summed over its counties), county (4) or municipality (6). " +
+                "A figure the register does not publish is null — never zero.",
+            inputSchema: {
+                code: z.string().describe(tercDetail),
+                kind: z.enum(["demography", "census"]).optional().describe("'demography' (voivodeship codes only) or 'census' (all three levels). Default: demography."),
+            },
+            call: (client, args) => {
+                const code = requireString(args, "code");
+                return args.kind === "census" ? client.regionCensus(code) : client.regionDemography(code);
+            },
+        },
+        {
+            name: "list_changes",
+            title: "List TERYT registry changes",
+            description: "The change feed of Poland's official registers: what GUS published in its TERYT update files — additions, modifications, moves, renames, orderings ('reordered' — a FORMATTING change, safe to filter out) and deletions, per registry (terc/simc/ulic), with the catalogue states (StanPrzed/StanPo) each side belongs to. " +
+                "A `deleted` row means the object left the catalogue — NOT that an address became invalid. Page with limit/offset; narrow with since/until (YYYY-MM-DD catalogue states) and dataset/type.",
+            inputSchema: {
+                since: z.string().optional().describe("Start catalogue state (YYYY-MM-DD): changes whose 'after' state is on or after this date."),
+                until: z.string().optional().describe("End catalogue state (YYYY-MM-DD), inclusive."),
+                dataset: z.enum(["terc", "simc", "ulic"]).optional().describe("The registry: terc (administrative units) | simc (localities) | ulic (streets). All three when omitted."),
+                type: z.string().optional().describe("Change type(s), comma-separated: added, modified, moved, renamed, reordered, deleted."),
+                limit: z.number().int().min(1).max(200).optional().describe("Maximum changes per page (1–200, default 50)."),
+                offset: offsetField,
+            },
+            call: (client, args) => client.changes(validated(normalizeArgs(args))),
+        },
+    ];
+}
+/** The arg names MCP hands over → the client's query objects, dropping empties. */
+function normalizeArgs(args) {
+    const out = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * The bridge between the MCP layer and the typed client: `registerTool`
+ * validates `args` against the tool's zod schema BEFORE the handler runs,
+ * so by the time `call` executes the shape is guaranteed — this cast
+ * records that guarantee, it does not create it.
+ */
+function validated(args) {
+    return args;
+}
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError(`@teryt24/mcp: "${key}" is required`);
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@teryt24/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP (Model Context Protocol) stdio server for the teryt24.pl API — 12 tools over the official @teryt24/api client: localities, streets, postal codes, address validation, geocoding, regions and the TERYT change feed.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "teryt24-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "poland",
+    "teryt",
+    "geocoding",
+    "address",
+    "llm",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dev-softify/teryt24-pl.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@teryt24/api": "^0.1.1",
+    "zod": "^4.3.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}