CityLike MCP Gateway — документация для агентов

CityLike — живой каталог бизнесов, мест и пеших маршрутов Центрального Орегона. Этот MCP-сервер открывает данные через стандартный протокол Model Context Protocol, чтобы любой агент (Claude, OpenCode, Gemini, MCP-клиенты) мог работать с ними.

Подключение

• Endpoint: https://citylike.me/mcp (streamable-http / MCP over HTTP)
• Протокол: MCP 2025-03-26
• Авторизация: гибридная — путеводитель открыт, полный каталог требует x-api-key (см. ниже)

Пример клиента (Python, mcp-sdk)

import asyncio, httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://citylike.me/mcp",
        http_client=httpx2.AsyncClient(headers={"x-api-key": "ВАШ_КЛЮЧ"}),
    ) as (read, write):
        async with ClientSession(read, write) as s:
            await s.initialize()
            tools = await s.list_tools()
            for t in tools.tools:
                print(t.name, "—", t.description)
            # вызов инструмента
            res = await s.call_tool("get_routes", {"city": "Bend"})

asyncio.run(main())

Через любой MCP-клиент (Claude / OpenCode / MCP-клиент)

mcp_servers:
  citylike:
    url: "https://citylike.me/mcp"
    headers:
      x-api-key: "ВАШ_КЛЮЧ"     # только для protected-инструментов

Доступ

Инструменты	Доступ	Ключ
Путеводитель (get_routes, get_route_stops, search_places, get_place_groups_by_city, nearby_places)	открыто	—
Бизнес-каталог + семантика + write (search_businesses, get_business, get_city_overview, top_businesses_by_category, recommend_places, search_places_semantic, search_routes_semantic, book_service, post_ad, business_faqs, ...)	закрыто	x-api-key

Получить ключ: обратитесь к владельцу citylike.me (для партнёров — по запросу). Для ключевых интеграций используются пер-агентные токены (формат citylike_...), которые изолируют один агент от другого и ведут учёт вызовов для биллинга.

Список инструментов (22)

Путеводитель (без ключа)

• get_routes(city?) — маршруты/туры с метриками
• get_route_stops(route_id) — точки тура по порядку
• search_places(query?, city?, category?) — места (музеи, парки, клиники...)
• get_place_groups_by_city(city?) — панорама города (сколько чего)
• nearby_places(lat, lon, category?, radius?) — места рядом

Бизнес и данные (ключ)

• search_businesses(query, city?, category?, min_rating?, top_n?) — поиск бизнесов. Выдача ранжирована: точное совпадение имени — первым, затем совпадения по словам имени (вес слова обратен его частоте в каталоге), затем совпадения только по описанию/городу. У каждого результата есть поле match:
• exact — имя совпало точно (регистр, пунктуация и «LLC/Inc» не важны);
• name — в имени есть значимое слово запроса;
• loose — совпадение только по описанию или городу, имя ни при чём. Если нужен контакт конкретного бизнеса, берите результат с match: "exact" — брать loose и показывать его телефон как телефон искомого бизнеса нельзя.
• count_businesses(query?, city?, category?, min_rating?) — точное количество записей по фильтрам + разбивка по городам и категориям. Отдельный тул, потому что остальные возвращают списки с потолком top_n: длина списка ≠ число бизнесов.
• get_business(id) / get_business_details(id) — профили
• top_businesses_by_category(category, city?) — топ по категории
• get_city_overview(city) — вся картина города одним вызовом
• search_semantic(query) — семантика бизнесов
• search_places_semantic(query, city?) — семантика мест
• search_routes_semantic(query, city?) — семантика маршрутов
• recommend_places(query, lat?, lon?) — рекомендации (смысл + близость)
• business_delta(id, after_seq?) — изменения (дешёвая синхронизация)
• business_faqs(id) — вопросы/ответы

Write (ключ)

• book_service(service_id, start_iso, customer) — бронь
• post_ad(kind, title, text, price?) — объявление
• add_business_detail(id, key, value) — дополнить профиль
• ask_business(id, question) — вопрос бизнесу

Провенанс записи (в каждом ответе)

Ни один ответ не отдаёт бизнес «голым»: у каждой записи есть блок provenance, потому что verified сам по себе значит только «запись совпала со своим источником при импорте», а не «данные полные и верные».

Поле	Значения	Что значит
category_source	import / classifier / …	откуда взялась категория
category_confidence	high / fixed / low / unchecked	уверенность в категории; low — знаем, что может быть неверна
description_quality	ok / thin / generated / junk / unchecked	generated/junk агентам не отдаются вообще
website_status	match / mismatch / unreachable / unchecked	сайт сверен с названием бизнеса
geo_source	google / osm / city / …	откуда координаты
last_checked	ISO-дата	когда запись проверяли
verified	bool	запись совпала со своим источником при импорте

Правила для агента:

• сайт показывайте только при website_status: "match" — поле оказалось ненадёжным, и mismatch означает, что URL ведёт на ДРУГУЮ организацию;
• контакт конкретного бизнеса берите только из результата с match: "exact";
• категорию при category_confidence: "low" не подавайте как факт;
• generated/junk описания вы не получите — это сделано намеренно, шаблон опаснее пустоты.

Данные

• 12 526 проверенных бизнесов (21 054 профиля в базе)
• 698 мест/достопримечательностей (OSM, с AI-описаниями)
• 7 AI-генерированных пеших маршрутов
• Гео: PostGIS + H3, семантика: pgvector (nomic-embed 768-d)