Istanbul MCP

Istanbul MCP

目录

• 快速开始
• 使用方法
• MCP 发现
• 安装
• 开发
• 部署

---

Istanbul MCP 是一个远程 Model Context Protocol 服务，可让支持 MCP 的 AI 工具、开发环境和基于 Agent 的工作流访问伊斯坦布尔的开放数据。

远程 endpoint：

https://istanbulmcp-production.up.railway.app/mcp/

为什么要创建它？

伊斯坦布尔有大量公共数据，涵盖停车、交通、道路拥堵、停水、水库蓄水量、图书馆、WiFi、博物馆、社区概况和开放数据等。这些数据分散在各类门户和服务中，但要直接在 AI 工具或 Agent 中使用，通常并不方便。

Istanbul MCP 填补了这一空缺。Codex、Claude、Cursor、OpenCode、Windsurf、Antigravity 等工具，或其他支持 MCP 的 Agent 系统，都可以通过同一个 endpoint 使用伊斯坦布尔的数据。

它的用途不只限于聊天界面。编写代码的 Agent、开展研究的工作流、生成数据分析的系统，或您自己的自动化流程，也都可以使用同一个 endpoint。

快速开始

无需密钥即可安装：添加 URL 即可使用。每个客户端均有 burst 限制；如需使用可选密钥／配额和 SQL 限制，请参阅访问指南。

使用 Codex CLI 添加：

codex mcp add istanbul --url https://istanbulmcp-production.up.railway.app/mcp/
codex mcp list

使用 Claude Code 添加：

claude mcp add istanbul --url https://istanbulmcp-production.up.railway.app/mcp/

Claude Desktop 和 Claude.ai（Settings > Connectors > Add custom connector）：

URL: https://istanbulmcp-production.up.railway.app/mcp/

然后开启新会话，并提出一个示例问题：

Taksim'e arabayla gideceğim. Yakındaki otoparkların boş yer sayısını, çalışma saatini ve haritadaki yerlerini gösterir misin?

通用 MCP 客户端配置：

{
  "mcpServers": {
    "istanbul": {
      "url": "https://istanbulmcp-production.up.railway.app/mcp/"
    }
  }
}

有些客户端要求使用 serverUrl 而不是 url，或要求 "type": "remote"、"transport": "http"。请使用末尾带有 /mcp/ 的 endpoint。

能做什么？

• 在 İBB 开放数据目录中搜索数据集。
• 返回数据集元数据、资源列表和 DataStore 架构。
• 使用安全的筛选条件和限制查询选定的 CKAN DataStore 资源。
• 返回伊斯坦布尔全市的交通拥堵指数。
• 按区、故障编号或与坐标的距离查询当前 İSKİ 停水故障。
• 列出 İSKİ 水库蓄水率和水库容量信息。
• 列出附近的 İSPARK 停车场，并提供容量、空余车位、开放／关闭状态、营业时间和地图链接。
• 对于按区查询停车场的问题，返回该区的停车场记录，而不生成虚假的中心点距离。
• 查找附近的 Metro İstanbul 站点、公共交通站点、WiFi 热点和空气质量监测站。
• 为 Kadıköy Rıhtım、Taksim、Levent 等已知地点生成出行摘要。
• 按行驶方向排序返回 İETT 线路信息和线路站点。
• 对于图书馆记录，提供地址、电话、营业时间和地图搜索链接。
• 利用社会援助、建筑存量和地震情景开放数据生成社区概况。
• 列出附近的电动汽车充电站、出租车站和集市。
• 按区和日期返回每周集市日程。

对于包含位置信息的记录，会返回 maps_url。对于只有地址信息的记录，可以使用 maps_search_url 和 location_precision=address_search；这些记录不会被呈现为精确坐标。

值班药店工具的响应指令要求为展示的每家药店添加可点击的地图链接。如果缺少坐标，则会根据药店名称和地址返回地图搜索链接。除非用户特别要求提供来源，否则最终回答不会显示 İBB 来源名称和链接；sources 字段仍会保留，以便进行技术追踪。回答中会保留数据时效性、结果数量限制以及电话确认提示。最终回答的格式由 MCP 客户端决定。

数据集探索

数据集研究是该项目的主要使用场景之一。可以直接询问某个主题在 İBB 开放数据目录中有哪些数据集、格式是什么，以及是否有可通过 DataStore 查询的资源等问题。

示例：

İBB açık veri kataloğunda müzelerle ilgili hangi veri setleri var?

示例结果：

• Kültür ve Turizm Bakanlığına Bağlı Müze Ziyaretçi Sayısı
• Müzelerimiz ve Ziyaretçi Sayıları
• İBB Müzeleri Lokasyon Çalışma Gün ve Saatleri

这些资源也可以查询。例如，博物馆位置资源会返回博物馆名称、区、地址、电话、营业时间和营业日等字段。

示例问题

Taksim'e arabayla gideceğim. Yakındaki otoparkların boş yer sayısını, çalışma saatini ve haritadaki yerlerini gösterir misin?
Levent yakınındaki metro istasyonları hangileri? Hat bilgisi ve harita linkleriyle listele.
500T hattı hangi duraklardan geçiyor? Durakları yönlerine göre sıralı ve harita linkleriyle göster.
İstanbul trafik yoğunluğu şu an hangi seviyede?
Şişli civarında aktif su kesintisi veya İSKİ arızası var mı?
10000511943 numaralı İSKİ arızasının detayını gösterir misin?
Baraj doluluk oranları şu an nasıl? En dolu 5 barajı listele.
İBB açık veri kataloğunda müzelerle ilgili hangi veri setleri var?
Beşiktaş'ta hangi kütüphaneler var?
Kadıköy Rıhtım çevresinde ulaşım seçenekleri neler?
Kadıköy Caferağa mahalle profili nedir?
Kadıköy'de yarın hangi pazar var?
Levent yakınındaki EV şarj istasyonlarını listele.

示例输出

询问 Taksim 附近停车场时，会返回停车场名称、距离、容量、空余容量、营业时间、开放/关闭状态和 Google Maps 链接。

询问 500T 线路时，会返回线路名称、票价、线路长度、预计行程时间以及两个方向按顺序编号的站点。

询问交通状况时，会返回全市交通指数、测量时间，以及说明该数据源不提供按道路划分的事故/事件详情的限制信息。

询问 İSKİ 故障时，会返回活动故障的区、街区、说明、开始时间、预计结束时间、大致几何中心和 Google Maps 链接。如果无法从 Railway 环境访问 İSKİ 实时地图数据源，则会使用结构化 snapshot fallback，并将结果标记为 freshness.status=stale。

询问水坝蓄水率时，会返回水坝名称、蓄水率、现有水量、容量和最高水位字段。如果无法访问实时数据源，则会启用官方 İSKİ API 或 snapshot fallback。

数据源

Istanbul MCP 使用来自以下来源的数据：

• İBB 开放数据门户（data.ibb.gov.tr）
• İBB City APIs（api.ibb.gov.tr）
• İSPARK 停车场服务
• Metro İstanbul 站点数据
• İETT SOAP 服务
• İSKİ 地图和水坝数据源
• İBB 城市地图值班药房服务（cbsproxy.ibb.gov.tr/?eczanews&ilceID=all）
• İBB 开放数据门户中的 İstanbulkart 充值点 DataStore 数据源（年度位置数据）
• İBB WiFi、图书馆、空气质量和街区概况数据源
• İBB EV 充电站和出租车站点 GeoJSON 图层
• İBB 每周集市和文化中心开放数据快照

所有工具结果均以标准响应模型返回：summary、data、freshness、sources、limits、warnings，以及必要时的 next_queries。

MCP 工具

默认接口包含 16 个只读工具。即使列表中未显示先前发布的某个工具名称，该工具仍可调用；MCP_LEGACY_TOOLS_ENABLED=true 会将旧名称也发布到列表中。相关能力并未移除，而是合并了附近地点/按区查询、水数据和 İETT 线路操作。 迁移表展示了旧调用 → 新调用的对应关系。

istanbul_health
istanbul_search_datasets
istanbul_get_dataset
istanbul_get_resource_schema
istanbul_query_resource
istanbul_datastore_query
istanbul_nearby
istanbul_traffic_status
istanbul_water_status
istanbul_mobility_nearby
istanbul_city_services_nearby
istanbul_neighborhood_profile
istanbul_transit_line
istanbul_transport_disruptions
istanbul_metro_accessibility_status
istanbul_market_schedule

工具	功能与示例
istanbul_health	服务和 SQLite 准备情况。
istanbul_search_datasets	按主题搜索 İBB 目录。
istanbul_get_dataset	数据集元数据和资源。
istanbul_get_resource_schema	资源列。
istanbul_query_resource	使用安全筛选和限制获取 CKAN 记录。
istanbul_datastore_query	对获准资源的完整且有限副本执行 SELECT/GROUP BY。SQL 指南。
istanbul_nearby	kind=parking,pharmacy,istanbulkart,social_facility,metro_station,air_quality,water_fault,city_feature。city_feature 类型：parking, metro_station, air_quality_station, public_transport_stop, wifi, ev_charging, taxi_stand, market。按坐标查询附近地点；查询停车场/药房时可按区筛选；查询 city_feature 时可使用 bbox。
istanbul_market_schedule	每周市场日程；支持 district、day（土耳其语/英语星期、今天/明天或 ISO 日期）和 limit。这是静态的每周日程，不代表实时开放状态。
istanbul_traffic_status	全市交通指数；不按道路细分。
istanbul_water_status	kind=faults：按区或故障编号查询；kind=dams：水坝蓄水率。
istanbul_mobility_nearby	查询地点/坐标的交通摘要；列出 39 个区内不含距离信息的停车场。
istanbul_city_services_nearby	查询地点周边的 WiFi；列出 39 个区内的图书馆和文化中心地址。
istanbul_neighborhood_profile	社会援助、建筑存量、地震情景；不是实时风险。
istanbul_transit_line	action=info,stops,departures；计划发车时间仅适用于主站点，不是 ETA。
istanbul_transport_disruptions	查询受支持运营方的最新状态和官方公告。
istanbul_metro_accessibility_status	设备总数和故障详情；不保证行程无障碍。

istanbul_ferry_schedules 默认关闭（FERRY_SCHEDULES_ENABLED=false）。 在已检查的出口环境中，Şehir Hatları 时刻表来源返回了 HTTP 403 challenge。 未经部署环境访问验证，请勿启用；现有的取消公告 relay 不提供时刻表。 取消公告仍由中断工具处理；来源错误将报告为 unavailable。

istanbul_transport_disruptions 仅检查四类已验证的官方中断范围：İETT 和 Metro İstanbul 的实时状态，以及 Metro 官方计划公告；Şehir Hatları 的取消/航班调整公告；Marmaray 官方紧急公告。Metro 实时状态和计划公告是分开的 sources[] 覆盖记录；如果其中一个无法读取，就不会给出笼统的“没有中断”摘要。istanbul_ferry_schedules 单独提供常规时刻表：先从官方时刻表索引中精确匹配完整路线，然后解析规范路线 HTML 表格。此结果带有 coverage_kind=published_timetable 和静态时刻表警告；它不是实时发船信息、延误或 ETA。mode、operator、line 和 limit 均为可选参数。line 会在 line_code 或 route_label 中执行不区分大小写的精确匹配。来源会缓存 120 秒；部分来源错误会通过 sources[].coverage_status=unavailable、freshness=unknown 和 warnings 显示。如果 Şehir Hatları 页面发布的是一般性公告或带日期的公告，系统不会编造线路代码；如果 relay 或直接访问官方网站被 403 阻止，则会明确报告为 unavailable。如果 Marmaray 返回 Angular 外壳，则会使用配置的 MARMARAY_API_BASIC_TOKEN 访问官方前端 API；如果 API 返回空列表，则视为已检查且结果为空。İDO、Turyol、Dentur、小巴和出租车合乘服务不在实时覆盖范围内，答复会在 limits[] 中说明。Metro 设备故障、路线引擎、ETA 和 GTFS stop_times 存档均不在这些工具的覆盖范围内。 istanbul_metro_accessibility_status 会从两个独立的官方来源读取 Metro İstanbul 设备/设施总数和当前设备故障详情：(1) GetFaultyEquipments JSON 服务提供按类别划分的正常/故障总数；(2) Metro İstanbul 官方故障页面提供线路/车站/设备位置、原因和计划恢复时间文本。每个来源单独缓存：数据在 120 秒内视为最新；自首次成功观测起，过期数据最多保留 15 分钟。可选的 line（完整线路代码或官方线路标签）、station 和 equipment_type（规范键或来源标签）筛选条件仅应用于详情列表；limit（默认 50，最多 100）仅截断筛选后的详情列表。汇总总数不受 limit 影响。如果一个来源失败，另一个来源经验证的数据会通过 partial_source 警告保留；如果两个来源都失败，则返回 ok=false/broken 信封。İnceleniyor 等未明确的恢复时间文本会原样保留；不会生成确切的恢复日期。响应包含 source、observed_at、fresh/stale/partial/broken 状态，以及以下明确限制：单个设备记录不会推断确切的车站/行程无障碍情况、替代路线或备用设备是否可用。

有关参数、行为和限制，请参阅 docs/tool-reference.md。

GTFS 站点位置

istanbul_nearby(lat=...,lon=...,types=["public_transport_stop"]) 和 istanbul_mobility_nearby 使用 İBB 官方 stops.csv 文件； 不会扫描 stop_times 来获取站点位置，也无需激活 DataStore。 BOM/; 和已知的带点分组坐标格式会按来源进行处理。 默认限额为 5 MiB / 50.000 行 / 20 秒；加载失败或不完整时，不会更改现有索引。仅在有限的 stale 窗口内，才会带警告提供旧数据；无法访问来源并不意味着“附近没有站点”。

这些是静态站点位置，不是实时到站信息、运营状态或新增的 next_departures 功能。有关 EV 充电、出租车站、每周集市和文化中心图层，请参阅静态城市图层。响应会保留来源时间以及已接收/已接受/已跳过的数量。详情和实时接受命令： GTFS 站点图层。

地点与区县解析

两个摘要工具都接受 district="Pendik" 这样的39 个区县名称。 district 不能与 place 和坐标同时使用。仅提供区县名称的 place="Pendik" 查询也会进入区县模式：

• 出行服务：仅提供全区停车场信息；不提供距离或其他交通组成部分。
• 城市服务：提供图书馆和文化中心地址；不查询 WiFi。
• 区县模式下不应用 radius_m；会应用结果数量限制。

Bostancı、Karaköy、Nişantaşı、Acıbadem, Kadıköy 和 Acıbadem, Üsküdar 现在会解析为注明来源版本的静态参考点。单独使用 Acıbadem 会返回 error_code=ambiguous_place；工具不会选择区县。 距离以参考点为中心，而非以所提供的地址为中心。目前尚不支持解析完整的街道/建筑地址，也未涵盖所有街区。 来源、许可与范围。

GTFS 计划停靠站发车信息

istanbul_next_departures(stop_query? | stop_id? | lat/lon?, line?, at?, radius_m?, limit?) 已实现，并在 2026-10-25 通过实时验收后于生产环境启用。数据源 默认值为 GTFS_SCHEDULE_ENABLED=false；实时部署使用 true。 使用完整的 stop_times.zip、服务日历和时刻表文件； stop_times.csv 仅用于预览，因此不予接受。会处理服务日期、日历 例外和 25:xx 时间；它不是实时 ETA 或路线规划器。 启动时会进行后台预热。预热期间，工具会返回 warming_up；首次加载约需两分钟。0.2.4 在启用 GTFS 时提供 18 个工具； 范围、设置和验收步骤。

如果不知道站点 ID，可使用 {"stop_query":"kadikoy","limit":10} 按 名称搜索。支持土耳其语/ASCII 字符和部分名称。此模式返回的是站点候选项， 而非发车信息。同名站点会按各自的 ID 和位置分别保留； 根据名称/地图选定站点后，再使用 stop_id 查询发车信息。 拼写建议带有 match_kind=suggestion；这不代表已确认匹配。 stop_query 只能与 limit 一起使用。不会推断区县/方向信息。 如果数据源中存在站点标牌代码（stop_code）、说明（stop_desc / platform_direction_text）和 location_type，则会予以保留；缺失项为 null。 每条发车信息都包含 realtime:false、schedule_relationship:STATIC 和 data_source。

istanbul_gtfs_snapshot_status() 显示当前本地时刻表的年龄、日历范围、 记录数和跳过的行数。它不会下载数据或检查实时数据源。 错误和结果截断使用通用的响应约定。

MCP 发现与提示词

使用 Python MCP SDK 2.3+ 时，同一个 /mcp/ endpoint 既支持旧版 initialize 请求，也支持 2026-07-28 版本中的 server/discover 流程。 0.2.4 在启用 GTFS 时提供 18 个工具，关闭时提供 16 个工具。除服务器指令外，还提供：

Resource URI	内容
istanbul://coverage	支持的功能、配置开关和范围限制
istanbul://sources	规范数据源、发布方、许可证/时效说明
istanbul://schema/catalog	目录发现流程、工具输入模式和查询限制

这些是本地元数据；读取它们不会调用外部 API，也不能证明实时数据源健康。 实际时效和数据源错误应从工具结果中读取。

如果客户端支持，可通过 prompts/list / prompts/get 选择四种土耳其语工作流：

• gunun_ozeti(district?) — 交通、供水和运输警报。
• mahalle_ozeti(district, neighborhood?) — 历史街区概况和边界。
• veri_kesfi(query) — 数据集 → 模式 → 有限记录查询。
• yolculuk_plani(origin, destination, line_code?) — 交通信息；不是路线引擎或实时 ETA。

选择提示词不会运行工具；只会生成工作流消息。 istanbul_nearby（包括药房）、istanbul_traffic_status、istanbul_water_status、 istanbul_transit_line 和 istanbul_transport_disruptions 还提供 outputSchema 和 structuredContent。会保留向后兼容的 JSON 文本和 Python dict 返回值。

有关协议详情、模式开销和验证，请参阅 MCP 接口。

客户端配置

Istanbul MCP 提供远程 Streamable HTTP MCP endpoint：

https://istanbulmcp-production.up.railway.app/mcp/

以下示例均已根据官方客户端文档核对。如果客户端要求使用其他字段名，请使用同一个 endpoint；例如，有些客户端使用 url，有些使用 serverUrl，还有些要求在 CLI 上使用 --transport http。

Codex CLI

codex mcp add istanbul --url https://istanbulmcp-production.up.railway.app/mcp/
codex mcp list

手动配置 ~/.codex/config.toml 的示例：

[mcp_servers.istanbul]
url = "https://istanbulmcp-production.up.railway.app/mcp/"

Claude Code

claude mcp add --transport http istanbul https://istanbulmcp-production.up.railway.app/mcp/
claude mcp list

JSON 配置示例：

{
  "mcpServers": {
    "istanbul": {
      "type": "http",
      "url": "https://istanbulmcp-production.up.railway.app/mcp/"
    }
  }
}

Claude Desktop

使用 Claude Desktop 需要付费订阅。

1. 打开 Claude Desktop。
2. 依次选择 Settings → Connectors → Add Custom Connector。
3. 输入信息：
   • Name： İstanbul MCP
   • URL： https://istanbulmcp-production.up.railway.app/mcp/
4. 点击 Add 按钮。
5. 开始使用 İstanbul MCP 工具。

Cursor

全局安装请使用 ~/.cursor/mcp.json，项目级安装请在仓库中使用 .cursor/mcp.json。Cursor 支持通过 url 字段配置远程 MCP 服务：

{
  "mcpServers": {
    "istanbul": {
      "url": "https://istanbulmcp-production.up.railway.app/mcp/"
    }
  }
}

OpenCode

opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "istanbul": {
      "type": "remote",
      "url": "https://istanbulmcp-production.up.railway.app/mcp/"
    }
  }
}

检查：

opencode mcp list

Windsurf

Windsurf/Cascade 配置位于 ~/.codeium/windsurf/mcp_config.json 文件中。对于 HTTP MCP，可以使用 serverUrl 或 url 字段：

{
  "mcpServers": {
    "istanbul": {
      "serverUrl": "https://istanbulmcp-production.up.railway.app/mcp/"
    }
  }
}

Devin / Devin CLI

Devin CLI 可以通过 devin mcp 命令或 JSON 配置文件添加远程 HTTP MCP 服务。Istanbul MCP 面向所有人开放，因此不需要 API key 或自定义 header：

devin mcp add istanbul --transport http --url https://istanbulmcp-production.up.railway.app/mcp/
devin mcp list
devin mcp get istanbul

Devin CLI 配置文件（.devin/config.json、.devin/config.local.json 或 ~/.config/devin/config.json）中的远程 HTTP 配置：

{
  "mcpServers": {
    "istanbul": {
      "url": "https://istanbulmcp-production.up.railway.app/mcp/",
      "transport": "http"
    }
  }
}

在 Devin 应用或要求填写 serverUrl 的 MCP 界面中，可以按以下方式提供相同的 endpoint：

{
  "mcpServers": {
    "istanbul": {
      "serverUrl": "https://istanbulmcp-production.up.railway.app/mcp/"
    }
  }
}

在企业 Devin 工作区中，MCP 服务或工具使用可能受管理员策略限制。如果 Devin 要求授予工具权限，请批准 Istanbul MCP 工具。

Google Antigravity

在本次检查中，无法从 Google Antigravity 的公开官方网站确认 MCP 的稳定 JSON 架构或文件路径。如果你使用 Antigravity，请以应用内的 MCP / raw config 界面为准。

如果应用内的 raw config 要求使用 mcpServers 和 serverUrl 格式，请使用以下配置；如果界面显示了不同的字段名称，请遵循 Antigravity 自身的架构：

{
  "mcpServers": {
    "istanbul": {
      "serverUrl": "https://istanbulmcp-production.up.railway.app/mcp/"
    }
  }
}

已检查的官方资源：

• Codex MCP 文档
• Claude Code MCP 文档
• Cursor MCP 文档
• OpenCode MCP servers 文档
• Windsurf/Cascade MCP 文档
• Devin CLI MCP 文档
• Devin MCP 文档

Registry 与数据处理

server.json 是仅限远程服务的 MCP Registry 清单。0.2.4 于 2026-10-25 注册到官方 MCP Registry， 并已通过 API 确认该记录的 active 状态。所有公共/旧版/可选工具都带有 title 和只读注解。发布前检查与命令。 Registry 发布、Railway 部署和 Claude directory 申请是独立步骤。 当前 Registry 记录。

版本历史。尚未选择代码许可证；也未添加 LICENSE 文件。 城市数据的许可证和使用条款与代码许可证相互独立。

安装官方发布者 CLI 后，检查清单并发布：

mcp-publisher validate server.json
mcp-publisher login github
mcp-publisher publish server.json
# Yayımlanmış sürümü Registry'den ayrıca doğrulayın
curl -fsS 'https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Batu1-1an%2Fistanbul-mcp&version=latest'

发布需要验证 GitHub 命名空间所有权。安装、凭据安全和从 Registry 检查结果的步骤请参阅发布指南。

数据处理/隐私说明 · 支持 / 问题反馈

HTTP 健康检查

工具监控与协议检查

在 0.2.6 中，/status 内的 tool_metrics 会显示每个工具的耗时、错误类型和共享缓存事件。不会记录参数、位置或密钥；计数器会在重启后重置。字段与限制。

CI 还会使用固定版本的官方 MCP 套件，在真实的本地服务上运行五个可执行场景。这是选定的 2025 年周期配置文件；并非完整认证或 2026 年协议测试。范围与报告。

pytest tests/test_tool_telemetry.py tests/test_conformance_runner.py
npm ci --prefix tests/conformance --ignore-scripts --no-audit --no-fund
python -m scripts.check_mcp_conformance

从浏览器直接连接 MCP

在 0.2.5 中，可通过 MCP_CORS_ALLOWED_ORIGINS 仅允许指定站点。 例如：https://uygulamaniz.example,http://localhost:5173。默认列表为空； 未添加站点地址时，不会允许浏览器 origin。不会影响不发送 origin 的 ChatGPT/服务器客户端。API 密钥、配额和速率限制均保持不变； 请勿将长期有效的密钥嵌入网页。设置与限制。

pytest tests/test_cors.py tests/test_api_auth.py tests/test_abuse_guard.py

存活状态 / 就绪状态

curl -fsS https://istanbulmcp-production.up.railway.app/healthz
curl -fsS https://istanbulmcp-production.up.railway.app/readyz
curl -fsS https://istanbulmcp-production.up.railway.app/status

/mcp 路径会重定向到 /mcp/。请在 MCP 客户端配置中直接使用 /mcp/。MCP 操作是 JSON-RPC POST 调用；普通 GET 请求并非通用健康检查。请使用上方的 HTTP 健康端点检查存活状态/就绪状态。

响应模型

工具会返回标准信封：

• ok
• summary
• data
• freshness
• sources
• limits
• warnings
• next_queries

服务以只读模式运行。它不会预订停车位、修改公共数据、提供紧急情况路线，也不会生成来源中不存在的字段。

已知限制

• 交通工具会返回全市范围的指数；不提供按道路划分的拥堵、事故或事件详情。
• 空气质量数据源可能会在部分站点返回最近读取时间，但 AQI 或 concentration 为空。
• İETT SOAP 服务在维护时段或数据源中断期间可能暂时无法响应。
• İSKİ 实时数据源可能会在部分 Railway 出口处超时。生产环境部署会通过目标地址固定且经过身份验证的 Cloudflare Worker 中继转发此流量。中继使用官方 e-Devlet 表格和 İSKİ JSON 数据源；成功响应会全局共享在 Workers KV 中，并通过 stale-while-revalidate 机制刷新。如果中继和直接数据源均不可用，则只能返回带有采集时间且未超过最大有效时长的快照。
• 截至 2026-10-23，api.ibb.gov.tr、data.ibb.gov.tr、cbsproxy.ibb.gov.tr、tesislerimiz.ibb.istanbul、www.metro.istanbul 和 İSKİ 主机不接受来自土耳其境外出口（Railway EU、Cloudflare、欧洲/美国的家庭互联网）的 TCP 连接；但可从土耳其的测量点访问。生产环境会通过 IBB_RELAY_* 将此流量经由伊斯坦布尔的中继发出。数据源连接最多等待 5 秒，连接超时后不会重试，同一主机在 60 秒内会快速返回 unavailable。
• İSKİ 故障距离基于数据源几何图形的近似中心计算，而非地址点。
• 完整路线规划、实时到达时间预测和地图 UI 不在此版本的范围内。
• 图书馆等部分记录包含的是地址而非坐标；此时会返回地图搜索链接，而非精确坐标。
• 并非所有 İBB 数据集都会规范化；目录搜索范围较广，而专用工具则聚焦于 MVP 范围内的字段。

开发

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m pip check
pytest
# SDK/protokol, yerel discovery ve output schema sözleşmeleri
pytest tests/test_mcp_protocol.py tests/test_mcp_discovery.py tests/test_mcp_structured.py
# İsteğe bağlı anahtarlı mod; değeri terminale yazdırmadan üretin:
export MCP_API_KEYS="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
# 20 soru × fresh/stale/broken × compact/legacy dispatch ve envelope sözleşmesi
pytest tests/test_tool_evals.py
# Tool tanımları, output schema ek maliyeti ve resource/prompt sayıları (byte, token değil)
python -m scripts.eval_tools
# GTFS kaynak/CSV/byte-row-timeout/stale ve gerçek registry regresyonları (offline)
pytest tests/test_gtfs.py tests/test_gtfs_regression.py tests/test_city_service.py tests/test_ckan_bounded.py
# Tam GTFS tarife ZIP, takvim/geceyarısı, bütçe/rollback ve opt-in MCP testleri
pytest tests/test_gtfs_schedule.py
# Ortak hata/kesilme sözleşmesi, durak metadata'sı ve yerel tarife sağlığı
pytest tests/test_response_contract.py tests/test_gtfs_snapshot_status.py
# EV/taksi/pazar/kültür statik katmanları ve pazar takvimi
pytest tests/test_city_open_data.py tests/test_city_service.py
# Yalnız erişebilen ortamda, tam GTFS ZIP indirir (opt-in; geçici DB kullanır)
RUN_LIVE_GTFS_SCHEDULE_TESTS=1 pytest -s tests/live/test_gtfs_schedule_source_live.py
# Resmî pinned registry şeması ve tüm tool yüzeylerinde title/readOnlyHint
pytest tests/test_registry_metadata.py
# SQL güvenlik/tamlık ve bounded HTTP testleri
pytest tests/test_guarded_sql.py tests/test_datastore_sql.py tests/test_ckan_bounded.py
# Dış kaynağa bağlanmadan gerçek yerel süreç + auth/kota/restart smoke testi
python -m scripts.smoke_mcp
python -m app.main

在干净环境中验证最低 Python 版本（可选使用 uv）：

uv run --isolated --no-project --python 3.11 --with-editable '.[dev]' python -m pytest

验证容器安装：

docker build -t istanbul-mcp:local .

第 A 层在 Python 3.11/3.12、真实进程和容器中的验证结果记录在 MCP 接口文档中。

本地服务器提供：

• GET /healthz
• GET /readyz
• GET /status
• POST /mcp/

实时 MCP 回归测试需选择启用后运行：

RUN_LIVE_MCP_TESTS=1 pytest tests/live
python scripts/live_mcp_uat.py
# Ayrı opt-in: yerel ASGI MCP + gerçek GTFS kaynağı; geçici DB, deploy yok
RUN_LIVE_GTFS_TESTS=1 pytest -s tests/live/test_gtfs_source_live.py

配置

重要缓存 TTL 变量：

• CKAN_CATALOG_CACHE_TTL_SECONDS
• CKAN_RESOURCE_CACHE_TTL_SECONDS
• IETT_LINE_CACHE_TTL_SECONDS
• IETT_STOPS_CACHE_TTL_SECONDS
• GTFS_STOPS_MAX_BYTES（5 MiB）、GTFS_STOPS_MAX_ROWS（50.000）、GTFS_STOPS_LOAD_TIMEOUT_SECONDS（20）
• GTFS_STOPS_CACHE_TTL_SECONDS（86.400）和 GTFS_STOPS_STALE_IF_ERROR_SECONDS（604.800；设为 0 可关闭）——限制与新鲜度
• SOURCE_CACHE_MAX_ENTRIES
• AIR_QUALITY_RATE_CAPACITY
• AIR_QUALITY_RATE_REFILL_PER_SECOND
• AIR_QUALITY_RATE_MAX_WAIT_SECONDS
• ISKI_FAULTS_CACHE_TTL_SECONDS
• ISKI_DAMS_CACHE_TTL_SECONDS
• ISKI_FAULTS_STALE_IF_ERROR_SECONDS
• ISKI_DAMS_STALE_IF_ERROR_SECONDS
• IBB_PHARMACY_BASE_URL（规范默认值：https://cbsproxy.ibb.gov.tr/?eczanews）
• IBB_PHARMACY_REQUEST_TIMEOUT_SECONDS、IBB_PHARMACY_REQUEST_ATTEMPTS
• IBB_PHARMACY_CACHE_TTL_SECONDS（300）和 IBB_PHARMACY_MAX_CACHE_AGE_SECONDS（1800）
• IBB_PHARMACY_STALE_IF_ERROR_SECONDS 和 IBB_PHARMACY_RATE_*
• MARMARAY_API_BASIC_TOKEN
• FERRY_SCHEDULES_ENABLED——默认值为 false；只有在部署环境中确认可访问时刻表后才启用。现有的取消公告 relay 不提供时刻表支持。
• SEHIR_HATLARI_RELAY_URL
• SEHIR_HATLARI_RELAY_TOKEN
• IBB_RELAY_BASE_URL、IBB_RELAY_TOKEN——同时提供这两个变量后，发往 İBB、Metro İstanbul、İSKİ、Şehir Hatları 和 TCDD Marmaray 主机的请求将通过土耳其境内的 relay 发出；URL 必须为 https，token 至少 32 个字符。设置方法：参阅 docs/deploy-railway.md 中的“İBB Relay”部分。

公开 MCP 的保护限制：

• CKAN_SQL_ALLOWED_RESOURCE_IDS——SQL 的运维人员 allowlist；默认为空。大小／时长／行数设置和硬性上限见 SQL 指南。
• MCP_AUTH_REQUIRED——默认值为 false（公开模式）。设为 true 后必须提供密钥，且服务器不会在未提供密钥时启动。
• MCP_API_KEYS——以逗号分隔的随机 Bearer 密钥；填写后会自动启用验证。
• MCP_API_KEY_DAILY_QUOTA——启用 auth 后，每个密钥的 UTC 每日配额；默认值为 10000，通过 SQLite 持久化。
• FORWARDED_ALLOW_IPS——用于读取客户端 IP 的可信代理；镜像中为 *，外部运行时默认为 127.0.0.1。
• MCP_LEGACY_TOOLS_ENABLED——也会在 tools/list 中发布旧版工具名称；默认为 false。无论此设置如何，旧名称始终可以调用。
• MCP_MAX_BODY_BYTES
• MCP_RATE_LIMIT_CAPACITY
• MCP_RATE_LIMIT_REFILL_PER_SECOND
• MCP_RATE_LIMIT_MAX_CLIENTS
• MCP_MAX_CONCURRENT_REQUESTS

İSKİ 资源访问和 fallback 变量：

• ISKI_REQUEST_TIMEOUT_SECONDS
• ISKI_REQUEST_ATTEMPTS
• ISKI_API_BASE_URL
• ISKI_API_BEARER_TOKEN
• ISKI_RELAY_BASE_URL
• ISKI_RELAY_TOKEN
• ISKI_RELAY_TIMEOUT_SECONDS
• ISKI_DAMS_SNAPSHOT_JSON
• ISKI_FAULTS_SNAPSHOT_JSON
• ISKI_FAULTS_SNAPSHOT_JSON_PART_1、ISKI_FAULTS_SNAPSHOT_JSON_PART_2、……
• ISKI_FAULTS_SNAPSHOT_CAPTURED_AT
• ISKI_DAMS_SNAPSHOT_CAPTURED_AT
• ISKI_FAULTS_SNAPSHOT_MAX_AGE_SECONDS
• ISKI_DAMS_SNAPSHOT_MAX_AGE_SECONDS

ISKI_RELAY_TOKEN 必须与 Cloudflare Worker 中的 RELAY_TOKEN secret 值一致。ISKI_API_BEARER_TOKEN 是 İSKİ 自有 Web 客户端使用的官方 API fallback 所必需的。Snapshot JSON 建议使用 {"captured_at":"...","payload":...} 封装格式；若使用旧版未封装的 payload 格式，则必须设置对应的 *_SNAPSHOT_CAPTURED_AT 变量。过期或未注明日期的 snapshot 不会作为活动数据提供。

示例环境变量请参阅 .env.example。

部署

生产环境中的服务运行在 Railway 上。Railway 部署说明请参阅 docs/deploy-railway.md。

基本命令：

railway status
railway config plan --detailed-exit-code

合并后，如果本地测试和 railway config plan --detailed-exit-code 均成功，可使用 railway up --detach --yes 进行受控部署。对于单独的基础设施变更，railway config apply 需要另行批准；关于迁移和回滚边界，请参阅 docs/deploy-railway.md。

项目计划

项目背景、路线图和 GSD 阶段产出保存在 .planning/ 下。