使用说明

Schwaizer

MCP Server: Geo MCP

An unofficial MCP server for interacting with Swiss building and geographic data via geo.admin.ch.

This is a community project by Schwaizer and is not an official implementation by the Swiss government.

关于Schwaizer

塑造瑞士人工智能的未来
通过负责任的人工智能采用，赋予瑞士企业和社会权力。
Schwaizer成立于2025年，是一家非营利组织，致力于在瑞士加速负责任地采用人工智能。

Schwaizer Geo-MCP服务器

MCP（模型上下文协议）服务器，提供从geo.admin.ch访问瑞士建筑登记处和地理位置的权限，并可选择公司位置丰富（通过Zefix MCP）。

特性

建筑物识别和搜索（BFS GWR： ch.bfs.gebaeude_wohnungs_register)
坐标转换（WGS84↔ 95级、03级↔ 等级95）
空间分析（半径搜索、面积统计）
公司位置整合（在建筑物注册的公司，公司→ 建筑物）
统一缺失数据语义（参见数据模型）

数据模型和缺失值（重要）

为了确保跨工具的下游处理一致，服务器使用以下约定：

缺失/未知值返回为 null.
坐标为数字（LV95东/北）。当坐标不可用时，字段 null.
邮政编码可用时为数字，否则为数字 null.
类别、楼层、住宅、面积、体积（如有）均为数字；否则 null.
当上游源不发布属性时（例如，一些建筑物没有 ganzwhg/住宅或 gvol*/卷），服务器返回 null 对于该字段（默认情况下不进行估计）。

规范化建筑对象片段示例：

{
  "egid": "2372938",
  "address": "Bahnhofquai 15",
  "municipality": "Zürich",
  "canton": "ZH",
  "postalCode": 8001,
  "city": "Zürich",
  "buildingCategory": 1060,
  "constructionYear": 1894,
  "numberOfFloors": 8,
  "numberOfDwellings": null,
  "area": 1229,
  "volume": null,
  "coordinates": { "easting": 2683276.64, "northing": 1247892.09 }
}

可用工具

坐标工具

wgs84_to_lv95
转换纬度/经度（WGS84，EPSG:4326）→ 95级（EPSG:2056）。

论据：

{ "latitude": 47.378177, "longitude": 8.540192 }

退货：

{ "easting": 2683187.XX, "northing": 1248065.XX, "system": "LV95" }

lv95_to_wgs84
转换LV95→ WGS84。

论据：

{ "easting": 2683188.02, "northing": 1248065.98 }

退货：

{ "latitude": 47.378177, "longitude": 8.540192, "system": "WGS84" }

lv03_to_lv95
基于网格的精确转换（LV03→ 95级）。

论据：

{ "easting": 683187.12, "northing": 248066.14 }

lv95_to_lv03
基于网格的精确转换（LV95→ 等级03）。

论据：

{ "easting": 2683188.02, "northing": 1248065.98 }

建筑工具（BFS GWR）

identify_building
识别LV95坐标处的建筑物。

论据：

{
  "easting": 2683260.75,
  "northing": 1247919.125,
  "tolerance": 12,
  "lang": "en"
}

返回：包含缺失值的规范化建筑对象数组（请参见数据模型）= null.

search_building
按地址或位置名称搜索建筑物。

论据：

{
  "address": "Bahnhofplatz 1, 8001 Zürich",
  "canton": "ZH",
  "lang": "en"
}

退货：

{
  "found": 1,
  "buildings": [ { "egid": "2372938", "... normalized fields ..." } ]
}

get_building_details
通过EGID获取标准化的建筑细节。

论据：

{ "egid": "263016183", "lang": "en" }

返回（示例）：

{
  "egid": "263016183",
  "address": "Hausmatt 508",
  "municipality": "Schlossrued",
  "canton": "AG",
  "buildingCategory": 1020,
  "constructionYear": 2016,
  "numberOfFloors": 4,
  "numberOfDwellings": 8,
  "area": 269,
  "volume": null,
  "coordinates": { "easting": 2649057.8, "northing": 1237971.7 }
}

空间分析

find_buildings_in_radius
使用可选过滤器查找WGS84点附近的建筑物。

论据：

{
  "lat": 47.378177,
  "lon": 8.540192,
  "radius_km": 0.5,
  "filters": {
    "constructionYearMin": 2000,
    "minFloors": 3
  }
}

返回摘要 buildings[]，每个条目包括地址、EGID（如果找到）、坐标（WGS84+LV95）、距离_m和关键属性。

get_area_building_statistics
市、州或bbox的汇总统计数据。

论据：

{
  "bbox": {
    "minLat": 47.376,
    "minLon": 8.538,
    "maxLat": 47.380,
    "maxLon": 8.543
  }
}

退货：

totalBuildings
constructionYearHistogram （十年箱）
buildingCategoryBreakdown （计数+百分比）
avgFloors
oldestBuilding, newestBuilding
residentialShare （根据类别范围计算；可能包括每个BFS类别的混合使用）

公司定位工具（可选）

这些工具用公司信息丰富了建筑数据。它们可以使用公共UID Webservice独立运行；为了获得最佳效果，请同时运行Schwaizer Zefix MCP，并在您的环境中配置其URL（如果适用）。

get_building_companies
列出在建筑地址注册的公司。

论据：

{ "egid": 2372938 }

退货：

{
  "egid": 2372938,
  "address": { "street": "Bahnhofquai", "houseNumber": "15", "postalCode": 8001, "city": "Zürich" },
  "totalCompanies": 5,
  "companies": [
    { "uid": "CHE-106.018.335", "name": "Nextlane Switzerland AG", "legalForm": "Corporation (AG)", "status": "ACTIVE" }
    // ...
  ]
}

find_company_buildings
解析公司UID的所有建筑物（总部+分支机构）。

论据：

{ "companyUid": "CHE-106.018.335" }

退货：

{
  "company": { "uid": "CHE-106.018.335", "name": "...", "legalForm": "...", "status": "..." },
  "locations": [
    {
      "locationType": "soap",
      "address": "Bahnhofquai 11, 8001 Zürich",
      "egid": "2372938",
      "coordinates": { "wgs84": { "lat": 47.37660, "lon": 8.54133 }, "lv95": { "easting": 2683276.64, "northing": 1247892.09 } },
      "buildingDetails": { "constructionYear": 1894, "buildingCategory": 1060, "floors": 8 }
    }
  ]
}

注意：为了获得更清晰的输出，调试详细信息被有意从响应中删除。

enrich_building_with_companies
返回建筑信息和详细的公司数据。

论据：

{ "egid": 2372938 }

analyze_building_occupancy
使用类别+公司存在对占用类型进行启发式分类。

论据：

{ "egid": 2372938 }

退货：

{
  "egid": 2372938,
  "address": "Bahnhofquai 15, 8001 Zürich",
  "buildingCharacteristics": { "category": 1060, "categoryType": "residential", "isMixedUse": false, "floors": 8, "dwellings": null, "constructionYear": 1894 },
  "commercialOccupancy": { "totalCompanies": 5, "hasCommercialActivity": true, "companiesPerFloor": "0.63" },
  "occupancyType": "residential_with_commercial"
}

安装

npm install

Schwaizer Zefix MCP快速入门（选项1--兄弟目录）

Schwaizer Geo MCP可以通过Schwaizer Zefix MCP用公司信息丰富建筑数据。最简单的设置是并排克隆两个存储库，并使用中已定义的本地依赖关系 package.json.

目录布局：

parent/
  schwaizer-zefix-mcp/
  schwaizer-geo-mcp/

为什么这样做：

Schwaizer Geo MCP package.json 在本地引用Zefix MCP：
```
"schwaizer-zefix-mcp": "file:../schwaizer-zefix-mcp"
```
将两个repos作为兄弟姐妹放置允许 npm install 在Schwaizer Geo-MCP中，无需额外配置即可在本地解析Zefix MCP。

步骤：

克隆两个存储库

# from your parent directory
git clone https://github.com/schwaizer/schwaizer-zefix-mcp.git
git clone https://github.com/schwaizer/schwaizer-geo-mcp.git

首先安装并配置Zefix MCP

cd schwaizer-zefix-mcp
cp .env.example .env
# Optional: only needed for Zefix REST enrichment (UID Public Services need no auth)
# ZEFIX_USERNAME=your_username
# ZEFIX_PASSWORD=your_password
# UID_PUBLIC_URL=https://www.uid-wse.admin.ch/V5.0/PublicServices.svc?wsdl
npm install

安装Schwaizer Geo-MCP

cd ../schwaizer-geo-mcp
cp .env.example .env
# Optional: adjust
# GEOADMIN_BASE_URL=https://api3.geo.admin.ch
# CACHE_TTL=300000
# LOG_LEVEL=info
npm install

运行两台服务器（单独的终端）

# Terminal 1
cd schwaizer-zefix-mcp
npm start

# Terminal 2
cd schwaizer-geo-mcp
npm start

在兼容MCP的客户端（例如Claude Desktop）中注册两台服务器

为Zefix添加一个MCP服务器条目
为Schwaizer Geo MCP添加第二个MCP服务器条目
您将看到两个可用的工具目录。Schwaizer Geo-MCP可以用公司信息丰富建筑物，您也可以直接调用Zefix工具。

验证

自 schwaizer-geo-mcp, npm ls schwaizer-zefix-mcp 应该对兄弟姐妹下决心 schwaizer-zefix-mcp 文件夹。
如果无法解决（路径/结构错误），请使用相同的父文件夹布局或考虑 npm link/工作空间。

备注

Zefix凭据是可选的：UID公共服务不需要身份验证；Zefix REST增强（例如，目的/注册日期）需要凭据。
所有缺失的值都将返回为 null （从来没有 "N/A")，在两台服务器上保持一致。

配置

复制 .env.example 到 .env 并调整：

# Optional: Custom base URL for geo.admin.ch API
GEOADMIN_BASE_URL=https://api3.geo.admin.ch

# Optional: Cache TTL in milliseconds (default: 5 minutes)
CACHE_TTL=300000

# Log level (trace|debug|info|warn|error|fatal), default: info
LOG_LEVEL=info

如果您打算与Schwaizer Zefix MCP集成以获取更丰富的公司数据，请单独运行它，并根据该服务器的README配置URL/环境。此服务器主要直接查询UID公共服务以获取地址，并在可用时通过Zefix REST进行丰富。

用法

运行服务器

npm start

工具调用示例

识别建筑物：

{
  "name": "identify_building",
  "arguments": {
    "easting": 2683260.75,
    "northing": 1247919.125,
    "tolerance": 12,
    "lang": "en"
  }
}

搜索建筑：

{
  "name": "search_building",
  "arguments": {
    "address": "Bahnhofplatz 1, 8001 Zürich",
    "canton": "ZH",
    "lang": "en"
  }
}

查找半径内的建筑物：

{
  "name": "find_buildings_in_radius",
  "arguments": {
    "lat": 47.378177,
    "lon": 8.540192,
    "radius_km": 0.5,
    "filters": { "constructionYearMin": 2000, "minFloors": 3 }
  }
}

获取区域统计数据：

{
  "name": "get_area_building_statistics",
  "arguments": {
    "bbox": { "minLat": 47.376, "minLon": 8.538, "maxLat": 47.380, "maxLon": 8.543 }
  }
}

联系建筑公司：

{
  "name": "get_building_companies",
  "arguments": { "egid": 2372938 }
}

API文件和资料来源

地理管理员服务：
- API概述：https://api3.geo.admin.ch/services/sdiservices.html
- 搜索API：https://api3.geo.admin.ch/rest/services/api/SearchServer
- MapServer标识：https://api3.geo.admin.ch/rest/services/api/MapServer/identify
- 高度服务：https://api3.geo.admin.ch/rest/services/height

缓存和速率限制

默认内存缓存TTL为5分钟(CACHE_TTL).
geo.admin.ch端点是公共的，并且速率有限；缓存减少了重复请求。
服务器重启时缓存重置。

发展

项目结构

  schwaizer-geo-mcp/
├── src/
│   ├── index.js                  # MCP server entry point
│   ├── config.js                 # Configuration loader
│   ├── api/
│   │   ├── geoadmin-client.js    # geo.admin.ch client
│   │   └── zefix-clients.js      # UID/Zefix clients (integration helpers)
│   ├── tools/
│   │   ├── building-tools.js     # identify/search/details
│   │   ├── coordinate-tools.js   # conversions
│   │   ├── spatial-analytics.js  # radius & area stats
│   │   └── company-location.js   # company & occupancy tools
│   └── utils/
│       ├── logger.js             # logging
│       └── cache.js              # caching
├── tests/
│   ├── setup.js
│   ├── unit/
│   └── integration/
├── docs/
│   └── CHANGELOG.md
├── .env.example
├── eslint.config.js
├── vitest.config.js
├── package.json
└── README.md

运行测试

npm test

代码检查

npm run lint

许可证

麻省理工学院

支持

美国地理: https://api3.geo.admin.ch/
此MCP服务器：在GitHub上打开一个问题