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.

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.