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忽略文件