MCP Open Data Hk

🚀 mcp-open-data-hk

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

🚀 クイックスタート

このサーバーを使うことで、DATA.GOV.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 - サポートされているファイル形式のリストを取得します。

📦 インストール

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

インストール後、MCP互換クライアント（Cursor、Claude Code、Claude Desktopなど）を設定するには、settings.jsonに以下を追加します。

{
  "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"]
    }
  }
}

💻 使用例

基本的な使用法

インストール後、AIアシスタントで以下のクエリを試してみてください。

1. "List some datasets from the Hong Kong government data portal via mcp-open-data-hk mcp."
2. "Find datasets related to transportation in Hong Kong. Use mcp-open-data-hk."
3. "What categories of data are available on DATA.GOV.HK? Use mcp-open-data-hk."
4. "Get details about the flight information dataset. Use mcp-open-data-hk."
5. "Search for datasets about weather in Hong Kong. Use mcp-open-data-hk."
6. "What file formats are supported by DATA.GOV.HK? Use mcp-open-data-hk."
7. "Find CSV datasets about population Use mcp-open-data-hk."
8. "Show me the most common tags in transport datasets Use mcp-open-data-hk."

AIは自動的にMCPサーバーの適切なツールを使って要求された情報を取得します。

📚 ドキュメント

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"
    }
  }
}

パッケージインストールアプローチはエンドユーザーに推奨され、ファイルパスアプローチはローカル開発とテストに便利です。

サーバーの拡張

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

1. @mcp.toolで装飾された新しい関数を追加します。
2. 関数とパラメータを説明する明確なドキュメント文字列を提供します。
3. 機能を実装します。
4. クライアントでテストします。

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

GitHubワークフロー

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

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

公開の設定（Trusted Publishing）

このプロジェクトは、APIトークンを使用するよりも安全なPyPIのTrusted Publishingを使用しています。設定するには:

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 - 追加の設定は必要ありません。

Trusted Publishingを使用すると、APIトークンを作成したりシークレットとして保存したりする必要がありません。

GitHub環境

Trusted Publishingを正常に機能させるには、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リリースが作成されます。

📄 ライセンス

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