Mcp Open Data Hk

mcp-open-data-hk

これは、香港政府の公式オープンデータポータルであるDATA.GOV.HKのデータにアクセスできるMCP（Model Context Protocol）サーバーです。

インストール

Smithery経由でインストールする

Smithery経由で、Claude Desktopにmcp-open-data-hkを自動的にインストールするには、次のようにします。

npx -y @smithery/cli install @mcp-open-data-hk/mcp-open-data-hk --client claude

uvを使用する（推奨）

uvを使用する場合、特別なインストールは必要ありません。uvxを使用して、_mcp-server-fetch_を直接実行します。

PIPを使用する

または、pipを使ってmcp-server-fetchをインストールできます。

pip install mcp-open-data-hk

インストール後、次のコマンドをスクリプトとして実行できます。

python -m mcp_open_data_hk

インストール後、settings.jsonに次の内容を追加して、MCP互換クライアント（Cursor、Claude Code、Claude Desktopなど）を設定します。

{
  "mcpServers": {
    "mcp-open-data-hk": {
      "command": "uvx",
      "args": ["mcp-open-data-hk"]
    }
  }
}

{
  "mcpServers": {
    "mcp-open-data-hk": {
      "command": "python",
      "args": ["-m", "mcp_open_data_hk"]
    }
  }
}

機能

このサーバーは、DATA.GOV.HK APIを操作するために次のツールを提供します。

1. list_datasets - データセットIDの一覧を取得します
2. get_dataset_details - 特定のデータセットの詳細情報を取得します
3. list_categories - データカテゴリの一覧を取得します
4. get_category_details - 特定のカテゴリの詳細情報を取得します
5. search_datasets - 詳細オプションを指定して、検索語でデータセットを検索します
6. search_datasets_with_facets - データセットを検索し、ファセット形式の結果を返します
7. get_datasets_by_format - ファイル形式別にデータセットを取得します
8. get_supported_formats - サポートされているファイル形式の一覧を取得します

ツール

list_datasets

DATA.GOV.HKからデータセットIDの一覧を取得します

パラメーター：

• limit（省略可）：返すデータセットの最大数（デフォルト：1000）
• offset（省略可）：返す最初のデータセットのオフセット
• language（省略可）：言語コード（en、tc、sc）—デフォルトは「en」

get_dataset_details

特定のデータセットの詳細情報を取得します

パラメーター：

• dataset_id：取得するデータセットのIDまたは名前
• language（省略可）：言語コード（en、tc、sc）—デフォルトは「en」
• include_tracking（省略可）：データセットとリソースにトラッキング情報を追加します—デフォルトはFalse

list_categories

データカテゴリ（グループ）の一覧を取得します

パラメーター：

• order_by（省略可）：並べ替えに使用するフィールド（'name'または'packages'）—非推奨です。代わりにsortを使用してください
• sort（省略可）：結果の並べ替え（'name asc'、'package_count desc'など）—デフォルトは「title asc」
• limit（省略可）：返すカテゴリの最大数
• offset（省略可）：ページネーション用のオフセット
• all_fields（省略可）：名前だけでなく、グループの完全な辞書を返します—デフォルトはFalse
• language（省略可）：言語コード（en、tc、sc）—デフォルトは「en」

get_category_details

特定のカテゴリ（グループ）の詳細情報を取得します

パラメーター：

• category_id：取得するカテゴリのIDまたは名前
• include_datasets（省略可）：カテゴリのデータセット一覧（省略版）を含めます—デフォルトはFalse
• include_dataset_count（省略可）：パッケージの合計数を含めます—デフォルトはTrue
• include_extras（省略可）：カテゴリの追加フィールドを含めます—デフォルトはTrue
• include_users（省略可）：カテゴリのユーザーを含めます—デフォルトはTrue
• include_groups（省略可）：カテゴリのサブグループを含めます—デフォルトはTrue
• include_tags（省略可）：カテゴリのタグを含めます—デフォルトはTrue
• include_followers（省略可）：カテゴリのフォロワー数を含めます—デフォルトはTrue
• language（省略可）：言語コード（en、tc、sc）—デフォルトは「en」

search_datasets

package_search API を使用して、クエリ語でデータセットを検索します。

この関数は、データセットのタイトル、説明、その他のメタデータを対象に検索し、クエリ語に一致するデータセットを見つけます。高度な Solr 検索パラメーターに対応しています。

パラメーター：

• query（任意）：Solr クエリ文字列（例：「transport」、「weather」、すべてを対象とする「:」）。デフォルトは「:」です。
• limit（任意）：返すデータセットの最大数（デフォルト：10、最大：1000）
• offset（任意）：ページネーションのオフセット。デフォルトは0です。
• language（任意）：言語コード（en、tc、sc）。デフォルトは「en」です。

戻り値： 以下を含む辞書：

• count：一致したデータセットの合計数
• results：一致したデータセットのリスト（最大 limit 件）
• search_facets：検索結果のファセット情報
• has_more：さらに結果があるかどうかを示すブール値

search_datasets_with_facets

データセットを検索し、データをより適切に探索できるよう、ファセット付きの結果を返します。

この関数は、タグ、組織、その他のファセットごとに分類したデータセット数を表示することで、利用可能なデータの種類を調べる際に役立ちます。

パラメーター：

• query（任意）：Solr クエリ文字列。デフォルトは「:」です。
• language（任意）：言語コード（en、tc、sc）。デフォルトは「en」です。

戻り値： 以下を含む辞書：

• count：一致したデータセットの合計数
• search_facets：検索結果のファセット情報
• sample_results：一致したデータセットの最初の3件

get_datasets_by_format

特定のファイル形式のリソースを含むデータセットを取得します。

パラメーター：

• file_format：絞り込みに使用するファイル形式（例：「CSV」、「JSON」、「GeoJSON」）
• limit（任意）：返すデータセットの最大数。デフォルトは10です。
• language（任意）：言語コード（en、tc、sc）。デフォルトは「en」です。

戻り値： 以下を含む辞書：

• count：一致したデータセットの合計数
• results：一致したデータセットのリスト

get_supported_formats

DATA.GOV.HK がサポートするファイル形式の一覧を取得します。

戻り値： サポートされているファイル形式のリスト

ローカルでのテスト

テストスクリプトを実行：

python tests/test_client.py
python tests/debug_search.py
python tests/comprehensive_test.py

サーバーを直接実行：

python -m src.mcp_open_data_hk

単体テストを実行：

pytest tests/

パス設定について

パッケージとしてインストールすると、ファイルパスではなくモジュール名でサーバーを参照できます。ユーザーは完全なファイルパスを指定する必要がないため、より便利です。

インストール済みパッケージ：

{
  "mcpServers": {
    "mcp-open-data-hk": {
      "command": "python",
      "args": ["-m", "mcp_open_data_hk"]
    }
  }
}

ローカル開発（ファイルパス方式）：

{
  "mcpServers": {
    "mcp-open-data-hk": {
      "command": "python",
      "args": ["-m", "src.mcp_open_data_hk"],
      "cwd": "/full/path/to/mcp-open-data-hk"
    }
  }
}

エンドユーザーにはパッケージのインストール方式を推奨します。一方、ファイルパス方式はローカルでの開発やテストに便利です。

クエリの例

インストールしたら、AI アシスタントで次のクエリを試してください：

1. 「mcp-open-data-hk mcp 経由で、香港政府のデータポータルにあるデータセットをいくつか一覧表示してください。」
2. 「香港の交通に関するデータセットを検索してください。mcp-open-data-hk を使用してください。」
3. 「DATA.GOV.HK ではどのようなデータカテゴリを利用できますか？mcp-open-data-hk を使用してください。」
4. 「フライト情報データセットの詳細を取得してください。mcp-open-data-hk を使用してください。」
5. 「香港の天気に関するデータセットを検索してください。mcp-open-data-hk を使用してください。」
6. 「DATA.GOV.HK でサポートされているファイル形式は何ですか？mcp-open-data-hk を使用してください。」
7. 「人口に関する CSV データセットを検索してください。mcp-open-data-hk を使用してください。」
8. 「交通データセットで最もよく使われているタグを表示してください。mcp-open-data-hk を使用してください。」

AI は、MCP サーバーから要求された情報を取得するために、適切なツールを自動的に使用します。

トラブルシューティング

よくある問題

1. モジュールが見つからないエラー：ローカル開発の場合は pip install -e .、公開済みパッケージの場合は pip install mcp-open-data-hk を実行して、依存関係をインストールしたことを確認してください。

2. パスの問題：IDE の設定で、cwd がプロジェクトルートへの正しい絶対パスになっていることを確認してください。

3. 権限エラー：Unix システムでは、スクリプトに実行権限があることを確認してください：

   chmod +x src/mcp_open_data_hk/__main__.py
   

4. FastMCP が見つからない：次のコマンドでインストールしてください：

   pip install fastmcp
   

接続のテスト

問題が発生している場合は、接続を手動でテストできます。

1. 1つ目のターミナルでサーバーを実行します。

   python -m src.mcp_open_data_hk
   

2. 別のターミナルでテストクライアントを実行します。

   python tests/test_client.py
   

これが機能する場合、問題は IDE の設定にある可能性が高いです。

サーバーの拡張

src/mcp_open_data_hk/server.py にツールを追加して、サーバーを拡張できます。既存のパターンに従ってください。

1. @mcp.tool でデコレートした新しい関数を追加します
2. 関数とパラメーターについて説明する、明確な docstring を記述します
3. 機能を実装します
4. クライアントでテストします

サーバーは、@mcp.tool でデコレートされたすべての関数を MCP クライアントに自動的に公開します。

GitHub ワークフロー

このプロジェクトには、CI/CD 用の GitHub Actions ワークフローが含まれています。

1. CI ワークフロー：main ブランチへのプッシュまたは PR ごとに、複数の Python バージョン（3.10-3.12）でテストを実行します
2. 公開ワークフロー：main へのプッシュごとに TestPyPI へ自動的にビルドして公開し、バージョンタグ（v*.*.*）のプッシュ時に PyPI へ公開します
3. コード品質ワークフロー：プッシュまたは PR ごとに、コードのフォーマットと lint をチェックします
4. リリースワークフロー：タグがプッシュされると、GitHub リリースを自動的に作成します

公開の設定（信頼された公開）

このプロジェクトでは、API トークンを使うより安全な PyPI の信頼された公開を使用します。設定するには、次の手順に従います。

1. https://pypi.org/manage/account/publishing/ にアクセスし、次の情報を指定して新しい保留中のパブリッシャーを追加します。

   • プロジェクト名：mcp-open-data-hk
   • オーナー：GitHub のユーザー名または組織名
   • リポジトリ名：mcp-open-data-hk
   • ワークフロー名：publish.yml
   • 環境名：pypi

2. https://test.pypi.org/manage/account/publishing/ にアクセスし、同じ情報を指定して新しい保留中のパブリッシャーを追加します。ただし、環境名には testpypi を指定します。

3. GitHub リポジトリで「Settings」>「Environments」に移動し、2つの環境を作成します。

   • pypi - セキュリティのため、「Required reviewers」に自分のユーザー名を設定します
   • testpypi - 追加の設定は必要ありません

信頼された公開を使用する場合、API トークンを作成したり、シークレットとして保存したりする必要はありません。

GitHub 環境

信頼された公開を正しく機能させるには、GitHub リポジトリの設定で2つの環境を作成する必要があります。

1. pypi - この環境では、PyPI への公開時にセキュリティのための手動承認が必要です
2. testpypi - この環境では手動承認は不要で、TestPyPI への公開が自動的に行われます

これらの環境を作成するには、次の手順に従います。

1. リポジトリの「Settings」タブに移動します
2. 左側のサイドバーで「Environments」をクリックします
3. 「New environment」をクリックします
4. pypi 環境を作成し、「Required reviewers」を有効にして自分のユーザー名を指定します
5. 追加の設定なしで testpypi 環境を作成します

新しいバージョンのリリース

新しいバージョンをリリースするには、次の手順に従います。

1. pyproject.toml のバージョン番号を更新します
2. 変更をコミットします
3. 新しいタグを作成してプッシュします。

   git tag -a v1.0.0 -m "Release version 1.0.0"
   git push origin v1.0.0
   

または、付属のリリーススクリプトを使用します。

./release.sh 1.0.0

これにより公開ワークフローが自動的に開始され、パッケージがビルドされて TestPyPI と PyPI（タグ付きリリースの場合）に公開され、GitHub リリースが作成されます。

コントリビューション

コントリビューションを歓迎します。このプロジェクトへの貢献方法については、コントリビューションガイドと行動規範をお読みください。

プロジェクト構成

mcp-open-data-hk/
├── src/
│   └── mcp_open_data_hk/  # Main Python package
│       ├── __init__.py    # Package initialization
│       ├── __main__.py    # Package entry point
│       └── server.py      # Main MCP server implementation
├── tests/
│   ├── test_client.py     # Client test script
│   ├── debug_search.py    # Search functionality test
│   ├── comprehensive_test.py # Comprehensive functionality test
│   └── test_data_gov_hk.py # Unit tests
├── requirements.txt       # Python dependencies
├── pyproject.toml         # Project configuration
├── README.md             # This file
├── run_examples.sh       # Example commands script
├── install.sh            # Installation helper script
├── release.sh            # Release helper script
└── .gitignore            # Git ignore file

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。