norway-location-transport-mcp

MCP-сервер, который предоставляет ИИ-агентам структурированный доступ к норвежским данным общественного транспорта и геопространственным данным через бесплатные API Entur и Kartverket / Geonorge.

Два источника дополняют друг друга: для планирования поездок нужна геокодировка, для определения высоты — разрешение адресов, а административные запросы привязывают координаты к местам. Один сервер отвечает на практические локальные вопросы: «как добраться отсюда до Бергена?», «какая высота на этом маршруте?», «в какой коммуне находится этот адрес?», «есть ли рядом электросамокаты?».

Оба источника данных бесплатны, без платных тарифов и без API-ключей. Entur требует только самоидентифицирующий заголовок ET-Client-Name (см. ниже); Kartverket не требует ничего.

Инструменты

Геолокация и геоданные (Kartverket)

• search_address(query?, street?, number?, postal_code?, municipality_number?, max_results) — поиск официальных адресов по произвольному тексту или полям; поддерживает подстановочный знак *. Возвращает координаты и кадастровые номера.

• find_addresses_near(latitude, longitude, radius_m, max_results) — все адреса в радиусе от точки, с расстояниями.

• validate_address(address) — проверка и нормализация адреса в свободной форме (нечёткое сопоставление). Возвращает valid, нормализованное совпадение и альтернативы.

• search_place_names(query, max_results) — поиск официальных названий мест; возвращает тип объекта (Fjell, Innsjø, …), муниципалитет, фюльке и координаты. Поддерживает *.

• find_place_names_near(latitude, longitude, radius_m, max_results) — ближайшие именованные объекты к точке, с расстояниями.

• get_elevation(latitude, longitude) — высота рельефа по национальной модели рельефа (DTM).

• get_elevation_profile(path, samples) — высота, измеренная вдоль маршрута; возвращает профиль, а также общее расстояние, подъём и спуск.

• transform_coordinates(x, y, from_epsg, to_epsg) — преобразование между системами координат (например, WGS84 4326 → UTM33 25833).

• lookup_admin_unit(latitude?, longitude?, address?) — в какой коммуне и фюльке находится координата или адрес, с официальными кодами.

• lookup_property(address?, latitude?, longitude?, max_results) — кадастровые (matrikkel) идентификаторы (kommune / gnr / bnr / fnr) через открытый адресный реестр.

Общественный транспорт (Entur)

• resolve_stop_place(query, max_results) — преобразование места или адреса в идентификаторы остановок Entur (Stop Place IDs).

• find_stops_near(latitude, longitude, radius_m, max_results) — обратное геокодирование координаты до ближайших остановок.

• plan_trip(from_place?/from_latitude/from_longitude, to_place?/to_latitude/to_longitude, date_time?, arrive_by?, transport_modes?, walk_speed?, num_trip_patterns) — планирование поездки из точки А в точку Б; фильтрация по виду транспорта и скорости ходьбы. Возвращает варианты маршрутов с этапами, видами транспорта, длительностью и временем в реальном времени.

• get_departures(stop_place_id, count) — ближайшие отправления с остановки, с задержками в реальном времени, отменами и платформой.

• get_realtime_status(stop_place_id? | line_id?) — состояние в реальном времени: для остановки — количество вовремя/с задержкой/отменённых; для линии — активные транспортные средства и задержки.

• get_stop_accessibility(stop_place_id) — доступность для инвалидных колясок по каждой платформе и сводка. (См. примечание о доступности ниже.)

• list_quays(stop_place_id) — все платформы (посадочные площадки) на остановке, с кодами и координатами.

• get_fare_zones(stop_place_id) — тарифная зона (зоны), к которой относится остановка.

• find_shared_vehicles(latitude, longitude, range_m, form_factors?, count) — свободно плавающие шеринговые транспортные средства (велосипеды, электросамокаты, автомобили, мопеды) всех операторов.

• find_docking_stations(latitude, longitude, range_m, count) — док-станции с количеством доступных транспортных средств и свободных мест.

• get_vehicle_positions(codespace_id?, line_id?, max_results) — позиции транспортных средств в реальном времени с курсом, скоростью и задержкой.

Определения инструментов находятся в src/kartverket.ts и src/entur.ts, объединены в src/tools.ts и используются как stdio, так и HTTP точками входа.

Установка

npm install
npm run build
npm test

npm test запускает сервер через stdio и вызывает каждый инструмент против живых API.

Запуск

Через stdio (для большинства MCP-клиентов):

node dist/index.js

Через Streamable HTTP (для HTTP-клиентов):

node dist/http.js
# listens on http://localhost:3000/mcp  (override with PORT)

Требование к имени клиента Entur

Условия Entur требуют, чтобы каждый запрос содержал идентифицирующий заголовок ET-Client-Name в формате company-app. Этот сервер отправляет его в каждом запросе к Entur. Задайте собственное значение с помощью переменной окружения ET_CLIENT_NAME:

ET_CLIENT_NAME="acme-travelbot" node dist/index.js

Если не задано, используется значение по умолчанию из пакета. Kartverket не требует ни заголовка, ни ключа.

Использование с Claude Code

claude mcp add norway -- node C:\Users\trond\norway-location-transport-mcp\dist\index.js

Затем спросите, например: «Спланируй поездку из Осло S в Берген и скажи высоту Галдхёпиггена».

Удалённая версия (Cloudflare Workers)

worker/ содержит удалённое развёртывание: те же 21 инструментов, обслуживаемых через MCP Streamable HTTP, так что сервер можно добавить как коннектор claude.ai. Он использует те же определения инструментов, что и локальный сервер (src/tools.ts принимает z как параметр, поэтому работает и с локальным MCP SDK v1 / zod 3, и с SDK v2 / zod 4 воркера).

cd worker
npm install
npm run dev     # local test at http://127.0.0.1:8787/mcp
node test-http.mjs

Разверните его (нужна учётная запись Cloudflare и wrangler login):

cd worker
npm run deploy

Задайте имя клиента Entur как переменную воркера:

cd worker
npx wrangler secret put ET_CLIENT_NAME

После развёртывания добавьте запись remotes с вашим URL workers.dev в server.json.

Примеры вызовов

Получить ближайшие отправления из Осло S:

{ "name": "get_departures", "arguments": { "stop_place_id": "NSR:StopPlace:59872", "count": 5 } }

Спланировать поездку только на автобусе/трамвае с заданной скоростью ходьбы:

{ "name": "plan_trip", "arguments": {
  "from_place": "NSR:StopPlace:59872",
  "to_latitude": 59.95, "to_longitude": 10.78,
  "transport_modes": ["bus", "tram"], "walk_speed": 1.4
} }

Профиль высот вдоль короткого маршрута:

{ "name": "get_elevation_profile", "arguments": {
  "path": [{ "latitude": 61.636, "longitude": 8.312 }, { "latitude": 61.64, "longitude": 8.32 }],
  "samples": 20
} }

Преобразовать координату WGS84 в UTM33:

{ "name": "transform_coordinates", "arguments": { "x": 10.7461, "y": 59.9127, "from_epsg": 4326, "to_epsg": 25833 } }

Примечания и ограничения

• Координаты везде указаны в WGS84 (широта/долгота). API Kartverket запрашиваются с EPSG 4326, чтобы числа совпадали; EUREF89 (4258) отличается в Норвегии менее чем на метр.

• Доступность: бесплатный JourneyPlanner от Entur предоставляет данные о доступности для инвалидных колясок по каждой платформе. Более детальная информация об оборудовании (лифты, тактильная навигация) доступна только в аутентифицированном API Stop Register от Entur и здесь недоступна; инструмент сообщает об этом.

• Ограничение частоты запросов от любого из источников отображается как понятная ошибка с просьбой повторить попытку.

• Атрибуция: данные Kartverket / Geonorge и Entur распространяются под лицензией NLOD. Указывайте источники при отображении данных.

Как это работает

• src/index.ts работает с MCP через stdio (JSON-RPC на stdin/stdout). src/http.ts работает с MCP через Streamable HTTP с управлением сеансами. Оба создают один и тот же сервер через src/server.ts.

• Каждый инструмент объявляет схему ввода Zod с описаниями, которые LLM читает напрямую — для вызова инструмента не нужна внешняя документация.

• Результаты — это JSON-текст, сокращённый до того, что нужно агенту, а не необработанные ответы вышестоящих API.

• Никогда не пишите в stdout через console.log; это нарушает протокол stdio. Пишите в stderr.

Лицензия

MIT © Trond Bjørøy. Данные © Kartverket и Entur, под лицензией NLOD.