Mcp Open Data Hk

mcp-open-data-hk

这是一个 MCP（模型上下文协议）服务，可访问香港政府官方开放数据门户 DATA.GOV.HK 中的数据。

安装

通过 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"]
    }
  }
}

功能

此服务提供以下工具，用于与 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. 在一个终端中运行服务：

   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. 编写清晰的文档字符串，说明函数和参数
3. 实现功能
4. 使用客户端进行测试

服务会自动向 MCP 客户端公开所有使用 @mcp.tool 装饰的函数。

GitHub 工作流

此项目包含用于 CI/CD 的 GitHub Actions 工作流：

1. CI 工作流：每次向 main 分支推送或提交 PR 时，都会在多个 Python 版本（3.10-3.12）上运行测试
2. 发布工作流：每次向 main 分支推送时，都会自动构建并发布到 TestPyPI；对于版本标签（v*.*.*），则会发布到 PyPI
3. 代码质量工作流：每次推送或提交 PR 时，都会检查代码格式和 lint
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 发行版。

贡献

欢迎贡献！请阅读我们的贡献指南和行为准则，了解如何为此项目做贡献。

项目结构

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 许可证。