使用说明

mcp开放数据香港

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

安装

通过Smithery安装

通过以下方式自动安装mcp open-data hk for Claude Desktop 史密瑟里:

npx -y @smithery/cli install @mcp-open-data-hk/mcp-open-data-hk --client claude

使用紫外线（推荐）

使用时 uv 不需要特定的安装。我们将使用 uvx 直接运行 mcp服务器获取.

使用PIP

或者，您可以安装 mcp-server-fetch 通过pip：

pip install mcp-open-data-hk

安装后，您可以使用以下命令将其作为脚本运行：

python -m mcp_open_data_hk

安装后，通过在settings.json中添加以下内容来配置您的MCP兼容客户端（如Cursor、Claude Code或Claude Desktop）：

Using uvx

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

Using pip installation

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

特性

服务器提供以下工具与数据交互。香港政府API：

list_datasets -获取数据集ID列表
get_dataset_details -获取特定数据集的详细信息
list_categories -获取数据类别列表
get_category_details -获取特定类别的详细信息
search_datasets -使用高级选项按查询词搜索数据集
search_datasets_with_facets -搜索数据集并返回分面结果
get_datasets_by_format -按文件格式获取数据集
get_supported_formats -获取支持的文件格式列表

工具

列表_数据集

从DATA获取数据集ID列表。GOV.HK

参数：

limit （可选）：要返回的最大数据集数（默认值：1000）
offset （可选）：要返回的第一个数据集的偏移量
language （可选）：语言代码（en、tc、sc）-默认为“en”

获取_数据_详细信息

获取特定数据集的详细信息

参数：

dataset_id：要检索的数据集的ID或名称
language （可选）：语言代码（en、tc、sc）-默认为“en”
include_tracking （可选）：将跟踪信息添加到数据集和资源中-默认为False

列表_类别

获取数据类别（组）列表

参数：

order_by （可选）：要排序的字段（“name”或“packages”）-已弃用，请改用sort
sort （可选）：结果排序（“名称asc”、“package_count desc”等）-默认为“标题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”

搜索_数据集

使用package_Search API按查询项搜索数据集。

此函数在数据集标题、描述和其他元数据之间进行搜索，以查找与查询词匹配的数据集。它支持高级Solr搜索参数。

参数：

query （可选）：solr查询字符串（例如，“运输”、“天气”、“:“for all）-默认为”:"
limit （可选）：要返回的最大数据集数（默认值：10，最大值：1000）
offset （可选）：分页偏移量-默认为0
language （可选）：语言代码（en、tc、sc）-默认为“en”

退货：包含以下内容的词典：

count：匹配的数据集总数
results：匹配数据集列表（最多）
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助手尝试以下查询：

“通过mcp-opendata-hk mcp列出香港政府数据门户网站的一些数据集。”
“在香港查找与运输相关的数据集。使用mcp-open-data-hk。”
“data.GOV.HK上有哪些类别的数据？请使用mcp open data HK。”
“获取航班信息数据集的详细信息。使用mcp open data hk。”
“搜索香港天气数据集。使用mcp-opendata-hk。”
“DATA.GOV.HK支持哪些文件格式？请使用mcp open DATA HK。”
“使用mcp open data hk查找有关人口的CSV数据集。”
“显示运输数据集中最常见的标签使用mcp open data hk。”

AI将自动使用您的MCP服务器中的适当工具来获取所请求的信息。

故障排除

常见问题

未找到模块错误：确保您已安装了以下依赖项 pip install -e . 促进当地发展，或 pip install mcp-open-data-hk 对于已发布的包。
路径问题：确保 cwd 在IDE配置中，是指向项目根的正确绝对路径。
权限错误：在Unix系统上，确保脚本具有执行权限：
```
chmod +x src/mcp_open_data_hk/__main__.py
```
未找到FastMCP：安装时使用：
```
pip install fastmcp
```

测试连接

如果您遇到问题，可以手动测试连接：

在一个终端中运行服务器：
```
python -m src.mcp_open_data_hk
```
在另一个终端中，运行测试客户端：
```
python tests/test_client.py
```

如果这有效，则问题可能出在IDE配置中。

扩展服务器

您可以通过在中添加更多工具来扩展服务器 src/mcp_open_data_hk/server.py.遵循现有模式：

添加一个新功能，用 @mcp.tool
提供一个清晰的文档字符串，解释功能和参数
实现功能
与客户进行测试

服务器自动公开所有装饰有 @mcp.tool MCP客户。

GitHub工作流

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

CI工作流：在每次向主分支推送/PR时，跨多个Python版本（3.10-3.12）运行测试
发布工作流：每次向main推送时自动构建并发布到TestPyPI，在版本标记（v*.*.*）时自动构建和发布到PyPI
代码质量工作流程：检查每个推送/PR上的代码格式和linting
发布工作流：推送标签时自动创建GitHub版本

发布设置（受信任的发布）

该项目使用PyPI的可信发布，该发布比使用API令牌更安全。要设置它，请执行以下操作：

首选https://pypi.org/manage/account/publishing/并添加一个新的挂起的发布者：
- 项目名称： mcp-open-data-hk
- 所有者：您的GitHub用户名或组织
- 存储库名称： mcp-open-data-hk
- 工作流名称： publish.yml
- 环境名称： pypi
首选https://test.pypi.org/manage/account/publishing/并添加一个新的挂起的发布者，该发布者具有相同的信息，但使用 testpypi 作为环境名称。
在GitHub存储库中，转到“设置”>“环境”并创建两个环境：
- pypi -为安全起见，将“必需审阅者”设置为您的用户名
- testpypi -无需额外配置

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

GitHub环境

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

pypi -发布到PyPI时，此环境需要手动批准安全性
testpypi -此环境不需要手动批准，并将自动发布到TestPyPI

要创建这些环境，请执行以下操作：

转到存储库的“设置”选项卡
点击左侧边栏中的“环境”
点击“新建环境”
创建 pypi 环境，并使用您的用户名启用“必需审阅者”
创建 testpypi 无需额外设置的环境

发布新版本

要发布新版本，请执行以下操作：

更新中的版本号 pyproject.toml
提交更改

创建并推送新标签：

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

使用说明

mcp开放数据香港

安装

通过Smithery安装

使用紫外线（推荐）

使用PIP

特性

工具

列表_数据集

获取_数据_详细信息

列表_类别

get_category_details

搜索_数据集

search_datasets_with_facets

get_datasets_by_format

get_supported_formats

局部测试

运行测试脚本：

直接运行服务器：

运行单元测试：

了解路径配置

已安装的软件包：

本地开发（文件路径方法）：

查询示例

故障排除

常见问题

测试连接

扩展服务器

GitHub工作流

发布设置（受信任的发布）

GitHub环境

发布新版本

贡献

项目结构

许可证

相关 MCP

MySQL查询服务器

MongoDB 数据库 MCP 服务器

Wikidata API服务器

Ledger CLI MCP服务器

SQLite数据库管理工具

Supabase MCP服务器