内容
# TERYT MCP
TERYT MCP 服务器，用于官方 TERYT 注册。提供 GUS 关于领土单位、地点和街道的数据，作为助手和自动化的工具。
支持的集合：
- `TERC` - 省、县、市和单位类型；
- `SIMC` - 地点；
- `ULIC` - 街道；
- `WMRODZ` - 地点类型字典。
npm 包：`teryt-mcp`。
## 典型问题
以下是服务器的主要用法。
### 查找 TERYT 单位
提示：
```text
查找下西里西亚省的 TERYT 标识符。
```
工具：`search_units`
输入：
```json
{
"query": "dolnoslaskie",
"limit": 5
}
```
回复：
```json
{
"units": [
{
"confidence": 0.95,
"matchedBy": "exact_normalized_name",
"unit": {
"id": "02",
"name": "DOLNOŚLĄSKIE",
"stateDate": "2026-01-01",
"type": "省"
}
}
],
"stateDate": "2026-01-01"
}
```
### 查找地点
提示：
```text
查找名为克拉科夫的 SIMC 地点。
```
工具：`search_places`
输入：
```json
{
"query": "Kraków",
"limit": 5
}
```
回复：
```json
{
"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"
}
```
### 查找街道
提示：
```text
查找名为马尔沙尔科夫斯卡的 ULIC 街道。
```
工具：`search_streets`
输入：
```json
{
"query": "Marszałkowska",
"limit": 5
}
```
回复：
```json
{
"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"
}
```
### 从文本中识别地点和街道
提示：
```text
识别"Wieliszew Marszalkowska"并返回 TERC、SIMC 和 ULIC 标识符。
```
工具：`resolve_address`
输入：
```json
{
"query": "Wieliszew Marszalkowska",
"limit": 5
}
```
回复：
```json
{
"addresses": [
{
"confidence": 0.95,
"matchedBy": "exact_normalized_address",
"address": {
"id": "0008639-12400",
"unit": {
"id": "14-08-05-2",
"name": "Wieliszew",
"type": "鄉鎮"
},
"place": {
"id": "0008639",
"name": "Wieliszew"
},
"street": {
"id": "0008639-12400",
"code": "12400",
"name": "马尔沙尔科夫斯卡"
},
"stateDate": "2026-06-19"
}
}
],
"stateDate": "2026-06-19"
}
```
这不是地理编码。工具识别到地点和街道级别的注册标识符。对于仅包含地点的查询，请使用 `search_places`。邮政编码和建筑编号被可读错误地拒绝，因为它们不属于 TERYT。
### 检查特定标识符
提示：
```text
检查 TERYT 单位 02-01-01-1。
```
工具：`get_unit`
输入：
```json
{
"id": "02-01-01-1"
}
```
回复：
```json
{
"unit": {
"id": "02-01-01-1",
"name": "博莱斯瓦维茨",
"stateDate": "2026-01-01",
"type": "城市鄉鎮"
},
"stateDate": "2026-01-01"
}
```
对于缺失的标识符，回复为：
```json
{
"unit": null,
"stateDate": null
}
```
类似地：
- `get_place` 检查地点的 SIMC 标识符；
- `get_street` 检查街道的 ULIC 标识符。
## TERYT 中有什么，不在 TERYT 中有什么
该服务器故意保持在 TERYT 范围内。因此，它支持注册标识符和名称，但不假装是地理编码器或点地址注册。
在 TERYT 范围内：
- 省、县、市及其类型；
- 地点及其 SIMC 标识符；
- 街道及其 ULIC 标识符；
- 地点-单位和街道-地点关联；
- 来自本地快照的数据状态日期。
在 TERYT 范围外：
- 坐标；
- 地块；
- 建筑物；
- 邮政编码；
- 地址点的验证，例如检查街道上是否有建筑编号。
这些数据需要其他来源，例如用于地址点和坐标的 PRG/EMUiA/GUGiK，用于地籍的 EGiB 或用于邮政编码的单独 PNA 字典。如果需要这些功能，应作为单独的服务器或单独的有界上下文创建，而不是作为 TERYT 的隐藏附加功能。
## MCP 工具
所有工具都返回 `structuredContent`。
### `about`
返回有关包、作者、联系方式、存储库、服务器版本和本地数据同步状态的信息。
输入：
```json
{}
```
回复：
```json
{
"author": {
"name": "Maciej Ciemborowicz"
},
"contact": {
"email": "maciej.ciemborowicz@gmail.com"
},
"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 这里没有经典的 semver 数据版本。`version` 字段是本地同步清单中 `STAN_NA` 的数据状态日期。
### `health_status`
检查服务器是否响应。
输入：
```json
{}
```
回复：
```json
{
"ok": true
}
```
### `server_status`
返回服务器运行时状态。
输入：
```json
{}
```
回复：
```json
{
"serverName": "teryt-mcp",
"serverVersion": "0.1.13",
"frameworkVersion": "0.2.1",
"transport": "stdio",
"dataDir": "/path/to/teryt-data",
"database": {
"status": "available"
}
}
```
### `source_status`
显示本地数据库和 TERYT 源元数据状态。
输入：
```json
{}
```
回复：
```json
{
"datasets": [
{
"dataset": {
"code": "TERC",
"name": "领土单位",
"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`
使用官方 TERYT 数据构建或重建本地 SQLite 数据库。
输入：
```json
{
"mode": "missing"
}
```
模式：
```text
missing 仅在数据库不存在时构建
stale 如果数据库已存在且超过 24 小时，则重建
force 在锁定时重建数据库
```
如果数据库已存在且模式为 `missing`，则响应为：
```json
{
"status": "skipped",
"mode": "missing",
"databasePath": null,
"datasets": []
}
```
重建后响应为：
```json
{
"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`
搜索 TERC 单位。
输入：
```json
{
"query": "Boleslawiec",
"limit": 20
}
```
返回：
```json
{
"units": [],
"stateDate": "2026-01-01"
}
```
### `search_places`
搜索 SIMC 地点。
输入：
```json
{
"query": "Stara Wieś",
"limit": 20
}
```
返回：
```json
{
"places": [],
"stateDate": "2026-01-01"
}
```
### `search_streets`
搜索 ULIC 街道。
输入：
```json
{
"query": "Marszałkowska",
"limit": 20
}
```
返回：
```json
{
"streets": [],
"stateDate": "2026-01-01"
}
```
### `resolve_address`
搜索到地点和街道级别的地址候选项。
输入：
```json
{
"place": "Bolesławiec",
"street": "Marszałkowska",
"limit": 20
}
```
也可以传递 `query`，例如 `Marszalkowska Boleslawiec` 或 `ulica Marszalkowska w Boleslawiec`。如果客户端可以分离地点和街道，则优先使用 `place` 和 `street` 字段。
返回：
```json
{
"addresses": [],
"stateDate": "2026-01-01"
}
```
### `get_unit`
通过标识符获取 TERC 单位。
输入：
```json
{
"id": "02-01-01-1"
}
```
### `get_place`
通过标识符获取 SIMC 地点。
输入：
```json
{
"id": "0009876"
}
```
### `get_street`
通过标识符获取 ULIC 街道。
输入：
```json
{
"id": "0009876-00123"
}
```
## 匹配和排名
`matchedBy` 表示为什么返回结果：
```text
exact_code
exact_normalized_name
exact_normalized_address
prefix
contains
```
`confidence` 是搜索排名的结果，而不是注册的官方值。精确代码匹配具有最高优先级。包含搜索片段的匹配项排名较低。
搜索会规范化波兰字符，因此像 `Boleslawiec` 这样的查询可以找到 `Bolesławiec`。
## 安装
在没有全局安装的情况下运行：
```bash
npx -y teryt-mcp serve
```
全局安装：
```bash
npm install -g teryt-mcp
teryt-mcp serve
```
要求：
- Node.js `>=20.19.0`
在安装过程中，包会尝试使用官方 TERYT 数据创建本地 SQLite 数据库。如果初始同步失败，安装仍会成功。你可以稍后通过 CLI 或 `sync_database` 工具同步数据库。
在安装过程中跳过同步：
```bash
TERYT_MCP_SKIP_POSTINSTALL_SYNC=1 npm install -g teryt-mcp
```
## 连接到 MCP 客户端
用于 stdio 传输的配置：
```json
{
"mcpServers": {
"teryt": {
"command": "npx",
"args": ["-y", "teryt-mcp", "serve"]
}
}
}
```
在全局安装后：
```json
{
"mcpServers": {
"teryt": {
"command": "teryt-mcp",
"args": ["serve"]
}
}
}
```
在清除进程间缓存的环境中，设置固定数据目录：
```json
{
"mcpServers": {
"teryt": {
"command": "npx",
"args": ["-y", "teryt-mcp", "serve"],
"env": {
"MCP_DATA_DIR": "/absolute/path/to/teryt-data"
}
}
}
}
```
### Codex
Codex CLI 和 Codex IDE 扩展程序共享 `~/.codex/config.toml` 配置。VS Code 文件 `User/mcp.json` 不会在 Codex 中注册服务器。
通过以下命令添加全局安装的服务器：
```bash
codex mcp add teryt-mcp -- teryt-mcp serve
```
`~/.codex/config.toml` 中的等效项：
```toml
[mcp_servers.teryt-mcp]
command = "teryt-mcp"
args = ["serve"]
```
更改配置后，启动新进程或新的 Codex 会话，并通过 `codex mcp list` 或终端界面中的 `/mcp` 检查服务器。
## 首次同步
服务器可以在没有本地数据库的情况下返回状态，但搜索和查找需要 SQLite 数据库。
基本 CLI 命令：
```bash
teryt-mcp help
teryt-mcp about
teryt-mcp status
teryt-mcp source-status
```
强制同步：
```bash
npx -y teryt-mcp sync --force
```
或在全局安装后：
```bash
teryt-mcp sync --force
```
同步以原子方式保存数据库。读取进程应该看到旧数据库或新数据库，而不会看到部分写入的文件。
## CLI
CLI 是辅助工具。完整的函数集可通过 MCP 获得。
```bash
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
```
目前，CLI 仅支持 `search places` 的搜索。MCP 工具还提供单位、街道、地址识别和标识符查找。
示例：
```bash
teryt-mcp search places Boleslawiec --limit 1
```
回复：
```json
{
"places": [
{
"confidence": 0.95,
"matchedBy": "exact_normalized_name",
"place": {
"id": "0009876",
"name": "博莱斯瓦维茨",
"stateDate": "2026-01-01",
"unitId": "02-01-01-1"
}
}
],
"stateDate": "2026-01-01"
}
```
## HTTP
HTTP 可用于本地测试或自定义包装：
```bash
MCP_TRANSPORT=http PORT=3000 teryt-mcp serve
```
端点：
```text
GET /health
POST /tools/:toolName
```
示例：
```bash
curl -s http://127.0.0.1:3000/tools/search_places \
-H 'content-type: application/json' \
-d '{"query":"Kraków","limit":3}'
```
HTTP 响应包含 MCP 工具的结果：
```json
{
"structuredContent": {
"places": [
{
"confidence": 0.95,
"matchedBy": "exact_normalized_name",
"place": {
"id": "0000000",
"name": "克拉科夫",
"stateDate": "2026-01-01",
"unitId": "12-61-00-0"
}
}
],
"stateDate": "2026-01-01"
}
}
```
## 运行时配置
```text
MCP_TRANSPORT=stdio|http # 默认stdio
MCP_PORT / PORT # 默认3000用于HTTP
MCP_DATA_DIR # 数据库和同步清单目录
XDG_CACHE_HOME # 如果MCP_DATA_DIR未设置，则使用
MCP_LOG_LEVEL # debug|info|warn|error|silent
```
本地文件：
```text
<data-dir>/teryt.sqlite
<data-dir>/sync-manifest.json
<data-dir>/*.lock
```
新版本可能会更改 SQLite 架构。服务器检测到不兼容的数据库，并在 `missing` 模式下重新同步；也可以显式运行 `teryt-mcp sync --force`。
## 开发
适用于仓库开发人员：
```bash
pnpm install
pnpm build
pnpm quality
```
架构和契约详情：
- [docs/tools.md](docs/tools.md)
- [docs/data-sync.md](docs/data-sync.md)
- [docs/architecture/feature-clean-architecture.md](docs/architecture/feature-clean-architecture.md)
- [docs/architecture/runtime-ecosystem.md](docs/architecture/runtime-ecosystem.md)
## 许可证和数据源
项目代码：Copyright 2026 Maciej Ciemborowicz。仅根据 [European Union Public Licence 1.2](LICENSE) (`EUPL-1.2 only`) 授权使用。
TERYT 数据来自波兰统计局。有关其获取和处理的更多信息，请参阅 [NOTICE.md](NOTICE.md)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器