MCP Open Data Hk

🚀 mcp-open-data-hk

這是一個MCP（模型上下文協議）服務器，可讓你訪問香港政府官方開放數據門戶 DATA.GOV.HK 的數據。

🚀 快速開始

你可以按以下步驟安裝和配置 mcp-open-data-hk，並與MCP兼容的客戶端（如Cursor、Claude Code或Claude Desktop）配合使用。

📦 安裝指南

通過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支持的文件格式列表。

返回值： 支持的文件格式列表

💻 使用示例

安裝完成後，你可以使用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服務器中的適當工具來獲取所需信息。

🔧 技術細節

本地測試

運行測試腳本

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. 發佈工作流：每次推送到主分支時，自動構建併發布到TestPyPI；在版本標籤（v*..）上，自動發佈到PyPI。
3. 代碼質量工作流：在每次推送到主分支或創建PR時，檢查代碼格式和語法。
4. 發佈工作流：在推送標籤時，自動創建GitHub版本。

發佈設置（可信發佈）

本項目使用PyPI的可信發佈，比使用API令牌更安全。設置步驟如下：

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"，創建兩個環境：
   • pypi - 為了安全起見，將 "Required reviewers" 設置為你的用戶名
   • testpypi - 無需額外配置

使用可信發佈時，無需創建或存儲API令牌作為機密信息。

GitHub環境

為了使可信發佈正常工作，你需要在GitHub倉庫設置中創建兩個環境：

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許可證。

項目結構

mcp-open-data-hk/
├── src/
│   └── mcp_open_data_hk/  # 主要Python包
│       ├── __init__.py    # 包初始化
│       ├── __main__.py    # 包入口點
│       └── server.py      # 主要MCP服務器實現
├── tests/
│   ├── test_client.py     # 客戶端測試腳本
│   ├── debug_search.py    # 搜索功能測試
│   ├── comprehensive_test.py # 綜合功能測試
│   └── test_data_gov_hk.py # 單元測試
├── requirements.txt       # Python依賴項
├── pyproject.toml         # 項目配置
├── README.md             # 本文件
├── run_examples.sh       # 示例命令腳本
├── install.sh            # 安裝輔助腳本
├── release.sh            # 發佈輔助腳本
└── .gitignore            # Git忽略文件