mcp-open-data-hk

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

安装

通过 Smithery 安装

要通过 Smithery 自动安装 mcp-open-data-hk 到 Claude Desktop：

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）：

<details> <summary>使用 uvx</summary>

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

</details> <details> <summary>使用 pip 安装</summary>

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

</details>

功能

该服务器提供了以下工具与 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.tool 的函数暴露给 MCP 客户端。

GitHub 工作流

此项目包括 GitHub Actions 工作流用于持续集成/持续部署：

1. CI 工作流：在每次推送/合并请求到主分支时，在多个 Python 版本（3.10-3.12）上运行测试
2. 发布工作流：在每次推送至主分支时自动构建并发布到 TestPyPI，而在版本标签（v*.*.*）时发布到 PyPI
3. 代码质量工作流：在每次推送/合并请求时检查代码格式和代码风格
4. 发布工作流：当标签被推送到 GitHub 时自动创建 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 仓库中，进入“设置” > “环境”并创建两个环境：

   • pypi - 设置“需要审批的人员”为您的用户名以增加安全性
   • testpypi - 不需要额外配置

使用可信发布，无需创建或存储 API 令牌作为秘密。

GitHub 环境

为了使可信发布正确工作，您需要在 GitHub 仓库设置中创建两个环境：

1. pypi - 此环境在发布到 PyPI 时需要手动审批以增加安全性
2. testpypi - 此环境不需要手动审批，将自动发布到 TestPyPI

要创建这些环境：

1. 进入您的仓库的“设置”标签
2. 点击左侧边栏中的“环境”
3. 点击“新建环境”
4. 创建 pypi 环境并启用“需要审批的人员”并选择您的用户名
5. 创建 testpypi 环境，无需额外设置

发布新版本

要发布新版本：

1. 更新 pyproject.toml 中的版本号
2. 提交更改
3. 创建并推送新的标签：

   git tag -a v1.0.0 -m "发布版本 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/  # 主 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 忽略文件

许可证

此项目根据 MIT 许可证授权。