TERYT MCP

MCP server for the official Polish TERYT registry.

The server exposes TERC territorial units, SIMC localities, ULIC streets, and the WMRODZ locality type dictionary through MCP tools and a small CLI. It uses the published MCP Craftman packages:

• @mcp-craftman/core

• @mcp-craftman/node

• @mcp-craftman/cli

Status

This project is a single server package, not a monorepo. The reusable framework lives in the separate mcp-craftman repository and is consumed from npm.

Related MCP server: Koleo MCP Server

Requirements

• Node.js >=20.19.0

• pnpm 10.x

Install

pnpm install

Development

pnpm quality
pnpm build

pnpm quality delegates to mcp-craftman quality and runs static analysis, dependency checks, architecture tests, and the unit/integration/contract test suite.

Runtime

Build and run stdio transport:

pnpm build
node dist/main.js

Run HTTP transport:

MCP_TRANSPORT=http PORT=3000 node dist/main.js

Runtime configuration:

MCP_TRANSPORT=stdio|http
MCP_PORT / PORT
MCP_DATA_DIR
XDG_CACHE_HOME

CLI

pnpm build
node dist/cli.js status
node dist/cli.js source-status
node dist/cli.js sync --force
node dist/cli.js search places Kraków --limit 5

The CLI calls the same capabilities as MCP, so JSON output matches tool structuredContent.

Tools

The public tool registry is in src/mcp/registry.ts.

• health_status

• server_status

• source_status

• sync_database

• search_units

• search_places

• search_streets

• resolve_address

• get_unit

• get_place

• get_street

See docs/tools.md for schemas and behavior.

Documentation

• docs/tools.md - public MCP tools and CLI mapping.

• docs/data-sync.md - official TERYT download and SQLite build flow.

• docs/quality.md - local quality gates.

• docs/architecture/feature-clean-architecture.md - feature layout and dependency rules.

• docs/architecture/runtime-ecosystem.md - runtime flow and transports.

• docs/architecture/package-boundaries.md - boundary between TERYT and MCP Craftman.