Istanbul MCP

Istanbul MCP

目次

• はじめに
• できること
• MCP の探索
• セットアップ
• 開発
• デプロイ

---

Istanbul MCP は、イスタンブールに関するオープンデータを、MCP 対応の AI ツール、開発環境、エージェントベースのワークフローから利用できるようにする、リモートの Model Context Protocol サーバーです。

リモートエンドポイント：

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

なぜ作られたのか？

イスタンブールには、駐車場、交通、渋滞、断水、ダムの貯水率、図書館、WiFi、博物館、近隣地区のプロファイル、オープンデータなど、多くの公共データがあります。これらのデータはポータルやさまざまなサービスに分散していますが、AI 対応ツールやエージェントから直接利用するのは、たいてい実用的ではありません。

Istanbul MCP はこのギャップを埋めます。Codex、Claude、Cursor、OpenCode、Windsurf、Antigravity などのツールや、MCP に対応するさまざまなエージェントシステムから、単一のエンドポイントを通じてイスタンブールのデータを利用できます。

用途はチャットインターフェースに限りません。コードを書くエージェント、調査を行うワークフロー、データ分析を行うシステム、自作の自動化でも、同じエンドポイントを利用できます。

クイックスタート

セットアップにキーは不要です。URL を追加すれば動作します。クライアントごとにバースト制限が適用されます。任意のキー／クォータと 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/"
    }
  }
}

一部のクライアントでは、url の代わりに serverUrl、"type": "remote"、または "transport": "http" が必要です。末尾に /mcp/ を付けたエンドポイントを使用してください。

できること

• İBB オープンデータカタログでデータセットを検索できます。
• データセットのメタデータ、リソース一覧、DataStore スキーマを取得できます。
• 選択した CKAN DataStore リソースを、安全なフィルターと上限を設定して検索できます。
• イスタンブール全域の交通渋滞指数を取得できます。
• アクティブな İSKİ の断水情報を、地区、障害番号、または座標からの距離で検索できます。
• İSKİ のダム貯水率とダム容量の情報を一覧表示できます。
• 近くの İSPARK 駐車場を、収容台数、空き台数、営業状況、営業時間、地図リンクとともに一覧表示できます。
• 地区ごとの駐車場に関する質問では、架空の中心地点からの距離を生成せず、該当地区の記録を返します。
• 近くの Metro İstanbul の駅、公共交通機関の停留所、WiFi ポイント、大気質観測所を検索できます。
• Kadıköy Rıhtım、Taksim、Levent などの既知の場所について、モビリティの概要を作成できます。
• İETT の路線情報と停留所を、進行方向ごとに順序付けて返します。
• 図書館の記録では、住所、電話番号、営業時間、地図検索リンクを提供できます。
• 社会扶助、建物ストック、地震シナリオに関するオープンデータを使って、近隣地区のプロファイルを作成できます。
• 近くの EV 充電ステーション、タクシー乗り場、市場を一覧表示できます。
• 地区と曜日ごとの週次市場スケジュールを取得できます。

位置情報を含む記録では 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.

出力例

タクシム周辺の駐車場に関する質問では、駐車場名、距離、収容台数、空き台数、営業時間、営業中／閉鎖中の状況、Google Maps リンクが返されます。

500T 路線に関する質問では、路線名、運賃、路線の長さ、推定所要時間、両方向の停留所が順番とともに返されます。

交通状況に関する質問では、市全体の交通指数、測定時刻、およびこの情報源では道路別の事故／事象の詳細を提供していないことを示す制限情報が返されます。

İSKİ の障害に関する質問では、発生中の障害の地区、町域、説明、開始時刻、推定復旧時刻、おおよそのジオメトリ中心、Google Maps リンクが返されます。Railway 環境から İSKİ のライブマップ情報源にアクセスできない場合は、構造化されたスナップショットのフォールバックが使われ、結果は freshness.status=stale として示されます。

ダムの貯水率に関する質問では、ダム名、貯水率、現在の貯水量、容量、最大水位のフィールドが返されます。ライブ情報源にアクセスできない場合は、公式の İSKİ API またはスナップショットのフォールバックが使用されます。

データソース

Istanbul MCP は、次の情報源からのデータを使用します。

• İBB オープンデータポータル（data.ibb.gov.tr）
• İBB City APIs（api.ibb.gov.tr）
• İSPARK 駐車場サービス
• Metro İstanbul の駅データ
• İETT SOAP サービス
• İSKİ の地図およびダム情報源
• İBB City Map の当番薬局サービス（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。座標による近隣検索。parking/pharmacy は区単位、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 のチャレンジを返しました。 デプロイ環境からのアクセスを確認するまでは有効にしないでください。現在の欠航告知リレーは 運賃表を提供しません。欠航告知は運行障害ツールで引き続き確認でき、ソースエラーは unavailable として報告されます。

istanbul_transport_disruptions は、検証済みの公式な運行障害の範囲を 4 つのみ確認します。İETT と Metro İstanbul のライブ状況および Metro の公式な計画告知、Şehir Hatları の欠航／運航変更告知、Marmaray の公式な速報告知です。Metro のライブ状況と計画告知は、別々の sources[] カバレッジ記録です。いずれかを読み取れない場合、全体に「運行障害なし」という概要は表示されません。istanbul_ferry_schedules は通常の運賃表を別途扱います。まず公式の運賃表インデックスでルートを完全一致させ、次に canonical ルートの 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ı のページに一般的または日付付きの告知がある場合、システムは故障コードを作り出しません。リレーまたは公式ページへの直接アクセスが 403 で拒否された場合は、その旨を unavailable と明示して報告します。Marmaray が Angular シェルを返す場合は、設定済みの MARMARAY_API_BASIC_TOKEN を使って公式フロントエンド API を利用します。API が空のリストを返した場合は、確認済みの空の結果として扱われます。İDO、Turyol、Dentur、ミニバス、タクシー・ドルムシュはライブカバレッジに含まれず、その旨は回答の limits[] に記載されます。Metro の設備故障、ルートエンジン、ETA、GTFS の stop_times アーカイブは、これらのツールの対象範囲外です。 istanbul_metro_accessibility_status は、独立した2つの公式ソースから、Metro İstanbulの設備・施設の公式集計値と最新の設備故障の詳細を読み取ります。（1）GetFaultyEquipments JSONサービスから取得するカテゴリ別の稼働中／故障中の合計数、（2）公式Metro İstanbul故障ページから取得する路線／駅／設備の場所、原因、復旧予定の文言です。各ソースは個別にキャッシュされます。120秒間は最新データとして扱い、最初に正常に取得できた時点から最長15分間は古いデータを利用します。任意の line（完全な路線コードまたは公式路線名）、station、equipment_type（canonicalキーまたはソース上の名称）フィルターは詳細一覧のみに適用されます。limit（既定値50、最大100）は、フィルター適用後の詳細一覧のみを切り詰めます。概要の合計数は limit の影響を受けません。一方のソースに障害が発生した場合は、もう一方の検証済みデータを partial_source 警告とともに保持します。両方に障害が発生した場合は、ok=false／broken のエンベロープを返します。「調査中」のような未確定の復旧予定文言はそのまま保持し、確定した復旧日は生成しません。応答には 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停留所レイヤーを参照してください。

場所と区の解決

2つの概要ツールはいずれも、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 が返されます。ツールが区を選択することはありません。距離は、指定された住所ではなく、基準地点を中心に計算されます。番地や建物名の完全な解決、およびすべての地区への対応は、まだ実装されていません。 Kaynak, lisans ve kapsam.

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 を返します。初回読み込みには約 2 分かかります。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/ エンドポイントが、従来の initialize リクエストと、2026-07-28 バージョンで導入された server/discover フローの両方に対応します。 0.2.4 のツール数は GTFS 有効時に 18、無効時に 16 です。サーバーの指示に加えて、以下を提供します。

リソース URI	内容
istanbul://coverage	対応機能、設定ゲート、対象範囲の制限
istanbul://sources	標準データソース、公開元、ライセンス／更新状況に関する説明
istanbul://schema/catalog	カタログの探索フロー、ツールの入力スキーマ、クエリの制限

これらはローカルのメタデータです。読み込んでも外部 API は呼び出されず、ライブソースの 稼働状況を証明するものではありません。実際の更新状況やソースのエラーはツールの結果で確認してください。

クライアントが対応している場合は、prompts/list / prompts/get を使って 4 つのトルコ語ワークフローを選択できます。

• 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 エンドポイントを提供します。

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

以下の例は公式クライアントのドキュメントと照合済みです。クライアントが別のフィールド名を要求する場合も、同じエンドポイントを使用してください。たとえば、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 はリモート MCP サーバーに対して url フィールドをサポートしています：

{
  "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 やカスタムヘッダーは必要ありません：

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 画面では、同じエンドポイントを次のように指定できます：

{
  "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 に登録されました。 登録の active 状態は API で確認済みです。すべての Public/legacy/optional ツールに、 title と読み取り専用の annotation が設定されています。公開前チェックとコマンド。 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 パッケージの実行可能なシナリオを5つ、実際のローカル サーバーで実行します。これは選定された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 キー、クォータ、レート制限は維持されます。 長期間有効なキーを Web ページに埋め込まないでください。設定と制限。

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

Liveness／readiness

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 リクエストは 一般的なヘルスチェックではありません。Liveness／readiness には、上記の HTTP ヘルスエンドポイントを 使用してください。

応答モデル

ツールは標準のエンベロープを返します。

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

サーバーは読み取り専用で動作します。駐車場の予約、公的データの変更、緊急時の案内は行わず、ソースに存在しないフィールドも生成しません。

既知の制限

• 交通ツールは市全域の指数を返します。道路ごとの混雑状況、事故、または事象の詳細は提供しません。
• 大気質のソースは、一部の観測所で最終読み取り時刻を返す一方、AQI または concentration の値を空で返すことがあります。
• İETT SOAP サービスは、メンテナンス時間中やソースの停止時に、一時的に応答しないことがあります。
• İSKİ のライブソースは、一部の Railway エグレスからのアクセスでタイムアウトすることがあります。本番環境では、このトラフィックを固定宛先かつ認証付きの Cloudflare Worker relay 経由で送信します。Relay は公式の e-Devlet テーブルと İSKİ JSON ソースを使用し、成功した応答を Workers KV でグローバルに共有して、stale-while-revalidate で更新します。Relay と直接ソースの両方が利用できない場合は、capture 時刻が記録されており、最大経過時間の制限を超えていない snapshot のみ返されることがあります。
• 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_* を使用して、イスタンブールの 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 です。デプロイ環境から時刻表にアクセスできることを確認してから有効にしてください。現在のキャンセル通知リレーは時刻表に対応していません。
• SEHIR_HATLARI_RELAY_URL
• SEHIR_HATLARI_RELAY_TOKEN
• IBB_RELAY_BASE_URL、IBB_RELAY_TOKEN — 両方を設定すると、İBB、Metro İstanbul、İSKİ、Şehir Hatları、TCDD Marmaray のホストへのリクエストはトルコ国内のリレー経由で送信されます。URL は https で始まり、トークンは 32 文字以上である必要があります。セットアップについては、docs/deploy-railway.md の「İBB Relay」セクションを参照してください。

公開 MCP の保護制限：

• CKAN_SQL_ALLOWED_RESOURCE_IDS — SQL 用のオペレーター許可リストです。デフォルトは空です。サイズ、時間、行数の設定とハード上限については、SQL ガイドを参照してください。
• MCP_AUTH_REQUIRED — デフォルトは false（パブリックモード）です。true にするとキーが必須になり、キーなしではサーバーを起動できません。
• MCP_API_KEYS — カンマ区切りのランダムな Bearer キーです。値を設定すると認証が有効になります。
• MCP_API_KEY_DAILY_QUOTA — 認証が有効な場合の、キーごとの 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İ のデータソースへのアクセスとフォールバックの変数：

• 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 シークレット値と同じである必要があります。ISKI_API_BEARER_TOKEN は、İSKİ 自身の Web クライアントが使用する公式 API のフォールバックに必要です。スナップショット JSON には、できるだけ {"captured_at":"...","payload":...} のラッパーを使用してください。従来のラッパーなしのペイロード形式を使用する場合は、対応する *_SNAPSHOT_CAPTURED_AT 変数が必須です。期限切れまたはタイムスタンプのないスナップショットは、アクティブなデータとして提供されません。

環境変数の例については、.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/以下に保存されています。