Philippine Standard Geographic Code Mcp Server

PSGC MCP サーバー

フィリピン標準地理コード（PSGC）APIへのアクセスを提供し、フィリピンの階層的な地理データを利用できるModel Context Protocol（MCP）サーバーです。

特長

• 完全な地理階層：島嶼グループ、地域、州、市、自治体、バランガイ、地区にアクセスできます
• 検索機能：すべての階層にわたって、名前から地理エンティティを検索できます
• コードの検証：PSGCコードを検証し、完全な階層情報を取得できます
• リアルタイムデータ：公式PSGC APIに直接アクセスできます
• 型安全：信頼性の高いデータ構造を実現するため、TypeScriptで構築されています

インストール

NPMから（公開パッケージ）

npm install -g psgc-mcp

MCP クライアントの設定

Cursor/Windsurf

MCP設定ファイルに追加します：

{
  "mcpServers": {
    "psgc-mcp": {
      "command": "npx",
      "args": ["-y", "psgc-mcp"],
      "transport": "stdio"
    }
  }
}

Claude Desktop

Claude Desktopの設定に追加します：

{
  "mcpServers": {
    "psgc-mcp": {
      "command": "npx",
      "args": ["-y", "psgc-mcp"],
      "transport": "stdio"
    }
  }
}

ローカル開発

1. リポジトリをクローンします
2. 依存関係をインストールします：npm install
3. プロジェクトをビルドします：npm run build
4. ローカルで実行します：npm start

利用可能なツール

サーバーは、地理階層ごとに分類された、PSGCデータにアクセスするための包括的なツールセットを提供します。

島嶼グループのツール

• get_island_groups：すべての島嶼グループを一覧表示します。
• get_island_group：コード（例："luzon"）で特定の島嶼グループを取得します。
• get_island_group_regions：特定の島嶼グループに属するすべての地域を取得します。
• get_island_group_provinces：特定の島嶼グループに属するすべての州を取得します。
• get_island_group_districts：特定の島嶼グループに属するすべての地区を取得します。
• get_island_group_cities：特定の島嶼グループに属するすべての市を取得します。
• get_island_group_municipalities：特定の島嶼グループに属するすべての自治体を取得します。
• get_island_group_cities_municipalities：特定の島嶼グループに属するすべての市と自治体を取得します。
• get_island_group_sub_municipalities：特定の島嶼グループに属するすべての準自治体を取得します。
• get_island_group_barangays：特定の島嶼グループに属するすべてのバランガイを取得します。

地域のツール

• get_regions：すべての地域を一覧表示します。
• get_region：コード（例："130000000"）で特定の地域を取得します。
• get_region_provinces：特定の地域に属するすべての州を取得します。
• get_region_districts：特定の地域に属するすべての地区を取得します。
• get_region_cities：特定の地域に属するすべての市を取得します。
• get_region_municipalities：特定の地域に属するすべての自治体を取得します。
• get_region_cities_municipalities：特定の地域に属するすべての市と自治体を取得します。
• get_region_sub_municipalities：特定の地域に属するすべての準自治体を取得します。
• get_region_barangays：特定の地域に属するすべてのバランガイを取得します。

州のツール

• get_provinces：すべての州を一覧表示します。
• get_province：コード（例："012800000"）で特定の州を取得します。
• get_province_cities：特定の州に属するすべての市を取得します。
• get_province_municipalities：特定の州に属するすべての自治体を取得します。
• get_province_cities_municipalities：特定の州に属するすべての市と自治体を取得します。
• get_province_sub_municipalities：特定の州に属するすべての準自治体を取得します。
• get_province_barangays：特定の州に属するすべてのバランガイを取得します。

地区のツール

• get_districts：すべての地区を一覧表示します。
• get_district：コード（例："133900000"）で特定の地区を取得します。
• get_district_cities：特定の地区に属するすべての市を取得します。
• get_district_municipalities：特定の地区に属するすべての自治体を取得します。
• get_district_cities_municipalities：特定の地区に属するすべての市と自治体を取得します。
• get_district_sub_municipalities：特定の地区に属するすべての準自治体を取得します。
• get_district_barangays：特定の地区に属するすべてのバランガイを取得します。

市のツール

• get_cities：すべての市を一覧表示します。
• get_city：コード（例："012805000"）で特定の市を取得します。
• get_city_barangays：特定の市に属するすべてのバランガイを取得します。

市町村ツール

• get_municipalities：すべての市町村を一覧表示します。
• get_municipality：コード（例："012801000"）を指定して、特定の市町村を取得します。
• get_municipality_barangays：特定の市町村に属するすべてのバランガイを取得します。

下位市町村ツール

• get_sub_municipalities：すべての下位市町村を一覧表示します。
• get_sub_municipality：コード（例："133901000"）を指定して、特定の下位市町村を取得します。
• get_sub_municipality_barangays：特定の下位市町村に属するすべてのバランガイを取得します。

市／市町村統合ツール

• get_cities_municipalities：すべての市と市町村を一覧表示します。
• get_city_municipality：コードを指定して、特定の市または市町村を取得します。
• get_city_municipality_barangays：特定の市または市町村に属するすべてのバランガイを取得します。

バランガイツール

• get_barangays：すべてのバランガイを一覧表示します。
• get_barangay：コード（例："012805001"）を指定して、特定のバランガイを取得します。

検索と探索ツール

• search_by_name：すべての階層を対象に、名称で地理的エンティティを検索します。
• get_hierarchy：特定のPSGCコードの完全な階層を取得します。
• validate_code：地理コードが存在するかを検証し、その詳細を取得します。

利用可能なリソース

• 静的データ：すべての地理階層について、事前に読み込まれた静的データにアクセスします。
• 動的クエリ：パラメーター付きクエリを実行して、特定のデータセットを取得します。
• 階層データ：リソーステンプレートを使用して、任意のPSGCコードの完全な階層情報を取得します。

利用可能なテンプレート（プロンプト）

• 一般的なクエリ：地理に関する一般的な質問（例：「[province]の州都はどこですか？」）に、事前定義されたプロンプトを使用します。
• ガイド付き探索：地理的階層の探索を支援する対話型プロンプトです。
• データ検証：PSGCコードと地理名を検証するためのプロンプトです。

使用例

すべての地域を取得

{
  "tool": "get_regions",
  "arguments": {}
}

地域内の州を取得

{
  "tool": "get_provinces",
  "arguments": {
    "region_code": "130000000"
  }
}

名称で検索

{
  "tool": "search_by_name",
  "arguments": {
    "query": "Manila",
    "type": "city"
  }
}

完全な階層を取得

{
  "tool": "get_hierarchy",
  "arguments": {
    "code": "133900000"
  }
}

API リファレンス

サーバーは公式のPSGC API（https://psgc.gitlab.io/api/）に接続します。

PSGCコードの形式

PSGCコードは階層形式に従います。

• 島嶼グループ：010000000、020000000、030000000
• 地域：130000000（NCR）、140000000（CAR）など
• 州：133900000（Manila）、137400000（Cebu）など
• 市／市町村：133903000（Manila City）、137404000（Cebu City）など
• バランガイ：133903001（Barangay 1, Manila）など

開発

前提条件

• Node.js 18 以降
• npm または yarn

セットアップ

git clone https://github.com/your-username/psgc-mcp.git
cd psgc-mcp
npm install

ビルド

npm run build

開発モード

npm run dev

テスト

npm test

MCP Inspector で検査

npm run inspect

貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature-name
3. 変更を加えます
4. 新機能のテストを追加します
5. テストを実行します：npm test
6. 変更をコミットします：git commit -am 'Add feature'
7. ブランチにプッシュします：git push origin feature-name
8. プルリクエストを送信します

ライセンス

MIT License — 詳細についてはLICENSEファイルを参照してください。

サポート

問題や質問がある場合は、GitHubリポジトリでissueを作成してください。