内容
# PRG MCP
国家边界注册（PRG）MCP 服务器，用于波兰国家边界注册，是国家测量和制图局的官方注册机构。它提供本地的边界、领土属性、地址点和街道数据，作为辅助工具和自动化工具。
支持的数据集：
- 54 个 PRG 图层，总共 52 个边界和领土属性的 WFS 图层，以及 `A07` 地址点和 `A08` 街道；
- 本地数据覆盖、来源状态和范围规划。
npm 包：`prg-mcp`。
## 典型问题
以下是服务器的主要应用。
### 查找行政单位
提示：
```text
查找 Wieliszew 市镇。
```
工具：`search_areas`
输入：
```json
{
"category": "administrative",
"query": "Wieliszew",
"limit": 5
}
```
响应：
```json
{
"areas": [
{
"areaId": "opaque-id",
"category": "administrative",
"code": "1408032",
"layerId": "A03",
"layerTitle": "市镇边界",
"name": "Wieliszew 市镇",
"objectId": "gmina-wieliszew",
"snapshotId": 1
}
],
"source": {
"system": "PRG",
"layerIds": ["A00", "A01", "A02", "A03", "A04", "A05", "A06"],
"channels": ["wfs"]
},
"datasetState": "installed",
"syncedAt": "2026-06-22T00:00:00.000Z",
"coverage": {
"complete": true,
"installedPairs": ["A03:country:PL"],
"installedScopes": ["country:PL"],
"missingScopes": []
}
}
```
### 检查点所属区域
提示：
```text
点 EPSG:2180 637807, 486708 位于哪个市镇和县？</p>
```
工具：`locate_point`
输入：
```json
{
"category": "administrative",
"x": 637807,
"y": 486708,
"limit": 10
}
```
响应包含按确定性排序的 `matches` 和元数据 `source`、`datasetState`、`syncedAt` 和 `coverage`。
### 确定领土属性
提示：
```text
该点的司法管辖区是哪一个？</p>
```
工具：`locate_point`
输入：
```json
{
"layerIds": ["S03"],
"x": 637807,
"y": 486708,
"limit": 5
}
```
对于检察官，请使用图层 `P01-P03`，对于警察，请使用图层 `K01-K13`，对于机关，请使用图层 `U01-U11`。
### 查找地址点
提示：
```text
查找地址 Warszawa Zurawia 12A。</p>
```
工具：`search_addresses`
输入：
```json
{
"query": "Warszawa Zurawia 12A",
"voivodeshipCodes": ["14"],
"limit": 5
}
```
响应：
```json
{
"addresses": [
{
"addressId": "opaque-id",
"buildingNumber": "12A",
"localityName": "Warszawa",
"point": [637807, 486708],
"postalCode": "00503",
"postalCodeNote": "postal_code_is_prg_attribute_not_postal_service_validation",
"sourceScope": "woj:14",
"streetName": "Zurawia",
"voivodeshipCode": "14"
}
],
"datasetState": "installed",
"coverage": {
"complete": true,
"installedPairs": ["A07:voivodeship:14"],
"installedScopes": ["voivodeship:14"],
"missingScopes": []
}
}
```
邮政编码是 PRG 地址点的属性。这不是波兰邮政的运营商验证。
### 地址逆查找
提示：
```text
查找点 637807, 486708 的最近地址。</p>
```
工具：`reverse_address`
输入：
```json
{
"x": 637807,
"y": 486708,
"radiusMeters": 1000,
"voivodeshipCodes": ["14"],
"limit": 5
}
```
该工具具有严格的半径和候选人限制。不会在限制之外假装命中。
### 查找街道
提示：
```text
在 PRG 数据中找到 Zurawia 街道。</p>
```
工具：`search_streets`
输入：
```json
{
"query": "Zurawia",
"voivodeshipCodes": ["14"],
"limit": 5
}
```
要获取街道的详细信息和几何形状，请使用 `get_street`。
### 获取区域几何形状
提示：
```text
显示 Wieliszew 市镇的几何形状。</p>
```
工具：`get_area_geometry`
输入：
```json
{
"areaId": "opaque-id",
"maxVertices": 10000,
"toleranceMeters": 0
}
```
响应为 `EPSG:2180`。对于大导出，请使用 CLI `prg-mcp export` 而不是模型上下文的完整几何形状。
### 缺少本地数据
当所需范围未安装时，数据工具不会返回空列表。它们会返回 `DATA_NOT_INSTALLED` 错误，并提供有关缺少同步运行器构建的信息，例如：
```text
PRG 地址数据未针对请求范围安装。数据同步未在此版本中打包；使用配置的导入管道为 voivodeship 14 准备 PRG 地址数据。
```
## PRG 中有什么，不包括什么
该服务器故意坚持 PRG。因此，它支持官方边界、领土属性、地址点、街道和空间关系，但不假装是一个通用公共注册。
在 PRG 范围内：
- 国家、省、县、市镇、城市、测量单位和地块的边界；
- 统计、法院、检察官、警察、消防、边境、税务、林业、水和海洋区域；
- `A07` 地址点，位于 `EPSG:2180` 坐标系中；
- `A08` 街道及其几何形状；
- 状态日期、版本和本地快照的属性；
- 本地数据覆盖和官方来源状态。
超出 PRG 范围：
- 完整的 TERYT 字典、TERYT 变更历史和 PRG 以外的统计分类；
- PRNG 地理名称；
- EGiB 地块、建筑物、公寓和土地登记册；
- 波兰邮政的邮政编码验证；
- 路由、线路规划和本地同步范围以外的地址。
这些数据需要其他来源，例如 `teryt-mcp` 用于 TERYT，PRNG 用于地理名称，EGiB 用于地籍或单独的 PNA 字典用于邮政编码。
## MCP 工具
所有工具都返回 `structuredContent`。目前，公共 MCP 工具都是只读的。同步运行器不作为 `sync_data` 公开，直到来源和发布者被产品连接起来。
返回 PRG 数据的工具包括：
```text
source
datasetState
syncedAt
coverage
```
### 操作
#### `about`
返回有关包、作者、存储库和模式版本的信息。
输入：
```json
{}
```
#### `health_status`
检查服务器是否响应。
输入：
```json
{}
```
响应：
```json
{
"ok": true
}
```
#### `server_status`
返回运行时状态、数据目录、SQLite 文件以及 FTS5 和 R-tree 的可用性。
输入：
```json
{}
```
#### `list_layers`
返回具有本地可用性、范围和记录数的 54 个 PRG 图层目录。
输入：
```json
{
"limit": 100
}
```
#### `source_status`
显示已安装的覆盖范围和可选的源状态。
输入：
```json
{
"checkRemote": false
}
```
计划的同步模式：
```text
missing 仅下载缺少的范围
stale 下载过时的范围
force 重建指定范围
```
规划配置文件：
```text
administrative 基本行政边界
administrative-history 历史行政边界；需要 --archive-year
addresses 指定范围内的地址点和街道
boundaries-full 所有的 PRG 边界层
poland-full 波兰完整安装，需要明确确认 CLI
```
### 区域
#### `search_areas`
按名称、代码、类别、图层、有效日期和快照搜索一个单位、法院、办公室或区域。
输入：
```json
{
"query": "Krakow",
"category": "administrative",
"limit": 20
}
```
#### `get_area`
按 `areaId` 获取一个 PRG 对象，不含完整几何形状。
输入：
```json
{
"areaId": "opaque-id"
}
```
#### `get_area_geometry`
获取受控的 GeoJSON 几何形状，位于 `EPSG:2180`。
输入：
```json
{
"areaId": "opaque-id",
"maxVertices": 10000,
"toleranceMeters": 0
}
```
#### `locate_point`
找到 `EPSG:2180` 中覆盖点的区域。
输入：
```json
{
"x": 566000,
"y": 244000,
"category": "administrative",
"limit": 20
}
```
#### `relate_areas`
在单个对象和指定图层或类别之间找到有限的空间关系。
输入：
```json
{
"areaId": "opaque-id",
"layerIds": ["W01"],
"limit": 20
}
```
### 地址和街道
#### `search_addresses`
按自然文本或结构化字段搜索地址点。`query` 和 `structured` 互相排斥。
输入：
```json
{
"query": "Warszawa Zurawia 12A",
"voivodeshipCodes": ["14"],
"limit": 20
}
```
#### `get_address`
按 `addressId` 获取地址点。
输入：
```json
{
"addressId": "opaque-id"
}
```
#### `reverse_address`
在 `EPSG:2180` 点周围搜索最近的地址点。
输入：
```json
{
"x": 637807,
"y": 486708,
"radiusMeters": 500,
"voivodeshipCodes": ["14"],
"limit": 10
}
```
#### `search_streets`
搜索 `A08` 街道。
输入：
```json
{
"query": "Zurawia",
"voivodeshipCodes": ["14"],
"limit": 20
}
```
#### `get_street`
按 `streetId` 获取街道的详细信息和几何形状。
输入：
```json
{
"streetId": "opaque-id"
}
```
## 安装
无需全局安装即可运行：
```bash
npx -y prg-mcp serve
```
全局安装：
```bash
npm install -g prg-mcp
prg-mcp serve
```
要求：
- Node.js `>=22.0.0`；
- 带有 FTS5 和 R-tree 的 SQLite，由 `server_status` 或 `prg-mcp doctor` 检查。
PRG 数据不包含在 npm 包中。服务器可以在没有本地数据的情况下响应状态和工具目录，但搜索需要显式同步。
## 连接到 MCP 客户端
标准输入传输配置：
```json
{
"mcpServers": {
"prg": {
"command": "npx",
"args": ["-y", "prg-mcp", "serve"],
"env": {
"MCP_DATA_DIR": "/absolute/path/to/prg-data"
}
}
}
}
```
全局安装后：
```json
{
"mcpServers": {
"prg": {
"command": "prg-mcp",
"args": ["serve"],
"env": {
"MCP_DATA_DIR": "/absolute/path/to/prg-data"
}
}
}
}
```
### Codex
Codex CLI 和 Codex IDE 扩展共享配置 `~/.codex/config.toml`。VS Code 文件 `User/mcp.json` 不会在 Codex 中注册服务器。
只需使用以下命令添加全局安装的服务器：
```bash
codex mcp add prg-mcp -- prg-mcp serve
```
`~/.codex/config.toml` 的等效项：
```toml
[mcp_servers.prg-mcp]
command = "prg-mcp"
args = ["serve"]
[mcp_servers.prg-mcp.env]
MCP_DATA_DIR = "/absolute/path/to/prg-data"
```
更改配置后，请启动新的进程或新的 Codex 会话并通过 `codex mcp list` 或终端界面中的 `/mcp` 检查服务器。
### Claude Desktop 和 VS Code
Claude Desktop 和 VS Code 使用上述 `mcpServers` 配置。在清理缓存的环境中，请设置常量 `MCP_DATA_DIR`，否则服务器可能会在没有本地数据的情况下启动。
## 数据计划
服务器可以在没有本地数据库的情况下返回状态，但搜索和查找需要本地 SQLite 文件。公共同步运行器尚未打包；`setup` 返回估计值和 `syncAvailable: false`。
基本 CLI 命令：
```bash
prg-mcp tools
prg-mcp status
prg-mcp coverage
prg-mcp source-status
prg-mcp doctor
```
推荐的启动计划：
```bash
prg-mcp setup
```
显式范围的地址计划：
```bash
prg-mcp setup --profile addresses --teryt 14
```
波兰的完整安装很大，需要明确确认：
```bash
prg-mcp setup --profile poland-full --confirm-poland-full
```
## CLI
CLI 是辅助的。完整的函数集通过 MCP 提供。
```bash
prg-mcp serve
prg-mcp tools
prg-mcp setup
prg-mcp status
prg-mcp coverage
prg-mcp source-status
prg-mcp doctor
prg-mcp call list_layers '{}'
prg-mcp call search_areas '{"query":"Warszawa","category":"administrative","limit":5}'
prg-mcp call source_status '{"checkRemote":false}'
```
通过 CLI 导出几何形状：
```bash
prg-mcp export --layer A03 --id '<object-id>' --format geojson --crs EPSG:4326
```
## HTTP
HTTP 可用于本地测试或自定义包装器：
```bash
MCP_TRANSPORT=http MCP_PORT=3000 prg-mcp serve
```
端点：
```text
GET /health
POST /tools/:toolName
```
示例：
```bash
curl -s http://127.0.0.1:3000/tools/search_areas \
-H 'content-type: application/json' \
-d '{"query":"Krakow","category":"administrative","limit":3}'
```
HTTP 响应包含 MCP 工具的结果：
```json
{
"structuredContent": {
"areas": [],
"datasetState": "installed",
"coverage": {
"complete": true,
"installedPairs": ["A03:country:PL"],
"installedScopes": ["country:PL"],
"missingScopes": []
}
}
}
```
## 运行时配置
```text
MCP_TRANSPORT=stdio|http # 默认stdio
MCP_PORT / PORT # 默认3000 用于 HTTP
MCP_DATA_DIR # SQLite 数据库目录和同步元数据目录
MCP_CONFIG_DIR # 运行时配置目录
MCP_LOG_LEVEL # debug|info|warn|error|silent
PRG_SOURCE_TIMEOUT_MS # 单个源任务超时
PRG_MAX_DOWNLOAD_BYTES # 硬性下载大小限制
PRG_SYNC_CONCURRENCY # 并行下载数量
PRG_FRESHNESS_CHECK_MS # 源新鲜度检查的最小间隔
```
本地文件：
```text
<data-dir>/catalog.sqlite
<data-dir>/boundaries.sqlite
<data-dir>/addresses-<woj>.sqlite
<data-dir>/*.lock_concurrency # 并行下载数量
PRG_FRESHNESS_CHECK_MS # 源新鲜度检查的最小间隔
```
本地文件：
```text
<data-dir>/catalog.sqlite
<data-dir>/boundaries.sqlite
<data-dir>/addresses-<woj>.sqlite
<data-dir>/*.lock
```
新版本可能会更改SQLite模式。服务器和同步工具通过本地数据库的元数据检测模式状态。
## 开发
对于仓库开发人员：
```bash
pnpm install
pnpm build
pnpm quality
pnpm test:pack-smoke
```
波兰完整安装的本地基准测试：
```bash
PRG_DATA_DIR=/absolute/path/to/prg-data pnpm benchmark:full-poland
```
架构和合同详细信息：
- [docs/tools.md](docs/tools.md)
- [docs/data-sync.md](docs/data-sync.md)
- [docs/intent-selection.md](docs/intent-selection.md)
- [docs/tutorial.md](docs/tutorial.md)
- [docs/troubleshooting.md](docs/troubleshooting.md)
- [docs/provenance.md](docs/provenance.md)
- [docs/layer-coverage.md](docs/layer-coverage.md)
- [docs/release.md](docs/release.md)
## 许可证和数据来源
项目代码：Copyright 2026 Maciej Ciemborowicz。仅根据 [European Union Public Licence 1.2](LICENSE) (`EUPL-1.2 only`) 授权使用。
PRG 数据来自国家测量和制图局以及 [Geoportal.gov.pl](https://www.geoportal.gov.pl/pl/dane/panstwowy-rejestr-granic-prg/)。有关数据获取和处理的更多信息，请参见 [NOTICE.md](NOTICE.md)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器