Saudi Open Data Mcp

saudi-open-data-mcp

saudi-open-data-mcp 是一款面向生产环境设计的 MCP 服务，用于接入沙特阿拉伯开放数据源。

快速入门

git clone https://github.com/raheb77/saudi-open-data-mcp.git
cd saudi-open-data-mcp
uv sync --no-editable
export HTTP_AUTH_TOKEN="$(openssl rand -hex 32)"
uv run --no-editable saudi-open-data-mcp --version
uv run --no-editable saudi-open-data-mcp check-startup
uv run --no-editable saudi-open-data-mcp list

实时刷新和查询路径取决于当前上游数据源是否可用以及本地快照。评估时，请先运行上方的启动和目录命令；只有在测试实时数据源访问时，才运行 uv run --no-editable saudi-open-data-mcp refresh。

本项目不只是一个封装上游网站的 MCP 包装器。它的价值在于 MCP 之下的各个层面：

• 通过显式连接器隔离数据源
• 采用类型化标准化流程和规范记录契约
• 由注册表管理数据集元数据和健康状态元数据
• 提供面向 AI 的确定性资源和工具接口

目前的实现已精选并覆盖 SAMA、stats.gov.sa、沙特财政部，以及一个范围有限的 data.gov.sa 试点数据集。当前基线是一个以容器为先的内部 MCP 服务，同时仍支持通过 stdio 进行本地开发和基于命令的主机集成。

仓库还包含一个位于 dashboard/ 下的阿拉伯语 RTL 仪表板包。 该包仍为可选项，但在 main 分支上，它现在是一个轻量级实时客户端，通过 /mcp 和 /startupz 使用受管控的后端，并将 /readyz 保留为仅用于启动的兼容别名，而非独立后端或核心功能所需的运行时依赖。

许可证与发布边界

• 本仓库中的代码依据 Apache License, Version 2.0 授权。
• 本仓库不包含模型权重。
• 默认情况下，模型权重不依据 Apache-2.0 授权。
• 未来如发布模型权重，将另行规定其使用条款。

有关架构的信息，请参阅 ARCHITECTURE.md；有关初始数据源决策，请参阅 ADR-001；有关当前核心身份验证、审计和数据访问模型，请参阅 GOVERNANCE.md；有关运行时和持久性指导，请参阅 OPERATIONS.md；有关当前本地、容器和运行时拓扑，请参阅 DEPLOYMENT.md；有关简明的故障与恢复处理指南，请参阅 RUNBOOKS.md；有关当前持久化和备份／恢复边界，请参阅 PERSISTENCE.md；有关当前基线变更说明和迁移备注，请参阅 CHANGELOG.md。

系统的功能

• 通过显式连接器隔离已批准的沙特阿拉伯官方数据源
• 将有限范围内受支持的数据集标准化为类型化契约
• 通过注册表模型维护数据集元数据和健康状态元数据
• 提供小型、受管控的 MCP 接口，用于搜索、元数据、健康状态、预览、查询、下载和受控物化
• 基于同一核心提供轻量级本地 CLI
• 通过 JSON、兼容 Excel 的 XML 和文本优先 PDF 导出，将查询结果生成受管控的机构级文件

系统不具备的功能

• 它不是通用 BI 套件或报表平台
• 它不是覆盖范围广泛的国家级数据湖，也不是任意网站的爬虫
• 核心路径不包含 LLM 改写、语义搜索或 AI 生成的叙述式报告
• 它不会将 query_dataset 变成实时远程查询接口
• 它不宣称已具备全面面向公共互联网部署的成熟度或灾难恢复自动化能力
• 仪表板不是独立后端、控制平面或规范的机构级导出路径

值得信赖的原因

• 数据源边界明确，且仅使用经批准的数据源
• 规范化输出采用类型化契约，而非自由格式的传输负载
• 由注册表提供的元数据可将描述信息、健康状态和注意事项从临时请求时逻辑中分离出来
• query_dataset 和 download_dataset 始终仅在本地运行，而 preview_dataset 是唯一的混合路径，并会明确提供新鲜度、来源和降级情况
• HTTP 身份验证、范围明确的 RBAC、结构化审计日志以及描述当前状态的治理文档均已就绪
• 部署、运行手册和持久化要求均有明确文档说明，而非隐含其中

当前系统界面

界面	用途	当前状态
后端/核心	通过 /mcp 提供受治理的 MCP 服务，并提供 /startupz	主要运行时
CLI	在同一核心之上的轻量运维人员/工程师界面	已支持
仪表板	位于 dashboard/ 下的阿拉伯语 RTL UI 包	可选的 /mcp 和 /startupz 实时使用方
导出	基于受治理查询结果生成的机构级产物	当前通过 CLI 受治理的路径

当前部署适用场景

当前部署适用范围刻意限定为狭窄而实用的场景：

• 内部部署或由评估方控制的部署
• 可自托管或适用于主权托管的环境，能够运行一个 Python 服务或容器，并管理本地持久化存储
• 由运维人员控制身份验证令牌、角色包、注册表路径和快照路径
• 仅需访问连接器中已实现的经批准的官方数据源界面
• 使用 /mcp 的 MCP 感知型客户端或检查工具，以及用于本地主机集成的 CLI/stdio

就当前状态而言，“可自托管”或“适用于主权托管”意味着：

• 无需供应商托管的控制平面
• 无需托管搜索/索引层
• 除本地 SQLite 注册表外，无需托管数据库
• 持久化运行时状态可保留在由运维人员控制的磁盘或卷存储中

本仓库目前不承诺：

• 托管式 SaaS 运营
• 面向公共互联网的加固服务态势
• 多节点或高可用集群运行时
• 完整的企业级 IAM 或按用户授权
• 合规认证或主权云认证

支持范围

支持的数据源

• SAMA
• stats.gov.sa
• Ministry of Finance
• 一条范围有限的 data.gov.sa 试点路径

支持的数据集系列

• 当前已登记的 SAMA 高频货币和市场数据集
• stats.gov.sa 月度总体 CPI
• stats.gov.sa 季度总失业率
• stats.gov.sa 季度实际 GDP 增长率
• Ministry of Finance 季度总体预算余额

请参阅 DATASETS.md，了解当前规范数据集方向和当前范围有限的契约限制。

稳定部分与持续演进部分

目前已足够稳定，可供评估和运行：

• 当前 MCP 工具/资源界面
• 基于该界面的当前 CLI
• 当前身份验证/审计/治理模型
• 当前容器/运行时/部署方案
• 当前受治理的 CLI 导出路径

仍在有意持续演进：

• 数据源和数据集覆盖范围
• 面向 HTML/PDF 数据源的规范化能力
• 运维、备份和恢复的自动化程度
• 作为受治理核心的实时使用方，仪表板的运维弹性和跨界面一致性

按受众快速入门

• 评估者：
  • 从本 README 开始，然后阅读 CHANGELOG.md、ARCHITECTURE.md、GOVERNANCE.md 和 DEPLOYMENT.md
• 运维人员：
  • 从 CHANGELOG.md、DEPLOYMENT.md、OPERATIONS.md、RUNBOOKS.md 和 PERSISTENCE.md 开始
• 工程师：
  • 从 CHANGELOG.md、ARCHITECTURE.md、DATASETS.md、GOVERNANCE.md 开始；如需了解当前 UI/实时集成边界，请阅读 dashboard/README.md

当前架构

当前代码库围绕三层组织。

数据访问层

• connectors/ 定义了类型化连接器契约，以及当前面向特定数据源的连接器，涵盖 SAMA、stats.gov.sa、财政部和一个范围有限的 data.gov.sa 试点数据集。连接器解析会根据 descriptor.source 进行分派。
• storage/ 提供原始快照持久化，以及用于连接器负载的本地新鲜度辅助功能。
• httpx 是核心路径中唯一的 HTTP 客户端。

规范化与契约层

• normalization/ 包含数据源感知的字段映射、数据源感知的验证、规范化管道，以及当前的最小规范记录层。
• registry/ 负责数据集描述符、健康元数据、SQLite 持久化和确定性引导数据。
• 仅针对范围有限的受支持 JSON 结构生成规范记录：
  • 对象列表位于顶层
  • 包含对象列表 rows 的对象

面向 AI 的工具层

• resources/ 提供由注册表支持的只读资源视图。
• tools/ 基于注册表、本地快照以及预览/查询路径，提供确定性的 MCP 工具层。
• server.py 使用 FastMCP 接入当前的 MCP 接口。

当前已实现的 MCP 接口

当前公开的 MCP 接口刻意保持精简：

• resource://catalog
• resource://observability
• resource://policies
• dataset_metadata
• dataset_health
• download_dataset
• materialize_hot_set
• query_dataset
• search_datasets
• preview_dataset

目前各项功能如下：

• resource://catalog：以只读方式汇总已引导的注册表目录
• resource://observability：以只读方式分组汇总当前进程本地计数器，并提供原始计数器快照供内部运维人员使用
• resource://policies：以只读方式汇总当前面向数据的语义，包括说明为何 query_dataset 仍是主要分析接口，而 preview_dataset 仍采用混合模式
• dataset_metadata：通过 dataset_id 精确查找注册表中的数据集元数据
• dataset_health：通过 dataset_id 精确查找注册表中的健康元数据，并在可用时提供本地快照新鲜度证据
• download_dataset：通过 dataset_id 查询仅限本地的原始快照可用性
• materialize_hot_set：显式获取 Wave 1 热门数据集，并为安全的 SAMA 子集持久化本地快照
• query_dataset：仅限本地，对根据本地快照派生的规范记录进行精确匹配查询
• search_datasets：基于注册表，确定性地对数据集元数据进行子串搜索
• preview_dataset：通过规范的 dataset_id 精确预览，使用显式的本地／在线混合解析元数据，并在内部使用注册表管理的 source_locator 访问来源

当前接口的简明示例：

resource://catalog
resource://observability
resource://policies
dataset_metadata({"dataset_id": "sama-money-supply-weekly"})
dataset_health({"dataset_id": "sama-money-supply-weekly"})
download_dataset({"dataset_id": "sama-money-supply-weekly"})
materialize_hot_set({"include_optional": false})
query_dataset({"dataset_id": "sama-money-supply-weekly", "filters": {"week_end_date": "2024-01-13"}, "limit": 5})
search_datasets({"query": "money"})
preview_dataset({"dataset_id": "sama-money-supply-weekly"})

当前可用功能

• 架构文档和 ADR 已就绪，并与代码库保持一致。
• 已为 SAMA、stats.gov.sa、财政部以及一个范围有限的 data.gov.sa 试点数据集定义并实现类型化连接器契约。
• 可以在本地写入和读取原始负载快照。
• 仅根据文件系统证据，以确定性方式评估本地快照的新鲜度。
• 已实现注册表模型、SQLite 仓库行为和确定性引导数据。
• 注册表描述符现在会区分规范的 dataset_id 和特定来源的 source_locator。
• 已实现并按来源分发规范化字段映射、验证、流水线组合和最简规范记录提取。
• MCP 服务已接入可正常运行的接口，涵盖目录、元数据、健康状态、下载、物化、查询、搜索和预览。
• 已为当前安全的 SAMA 子集实现 Wave 1 热门数据集物化。
• 内部容器运行时可使用 Tier A 后台刷新，且默认保持关闭。
• 预览会根据描述符来源解析连接器，并使用当前规范化分发路径；它可能返回：
  • record_derivable
  • limited
  • failed
• 预览现在会提供明确的混合模式元数据，包括数据来源、新鲜度状态和解析结果。
• 查询和下载仅限本地操作，快照缺失时不会在线获取数据。
• 内部 HTTP 服务提供明确的 bearer-token 身份验证、能力检查、规范的 /startupz 启动探针，以及具有相同启动阶段语义的 /readyz 兼容别名。
• 精选的 upstream-canary 命令和定时工作流现在会针对已注册可查询金丝雀数据集的来源系列，验证在线的已批准数据集路径。
• 单元、集成、契约和冒烟测试均已纳入代码库并通过。

暂未实现的功能

• 不覆盖当前精选官方数据集之外的广泛来源类别
• 不支持语义搜索
• 核心流程中不使用大模型
• 不支持由连接器驱动的目录发现
• 除精选上游金丝雀子集外，不支持全系统健康评分或广泛的连接器运行时间监控
• download_dataset 或 query_dataset 不支持远程回退
• 尚无成熟的规范记录层，可将每种来源负载结构转换为最终业务记录
• 除当前由注册表管理的 dataset_id 和单一 source_locator 外，不支持通用规范身份转换

需要明确的一项重要限制：preview_dataset 使用真实的连接器和规范化流程，但规范化层对于 HTML/文本负载仍可能返回 limited 结果，目前也不保证能生成最终的规范化领域记录。

另一项重要限制：query_dataset 仅适用于可规范化为当前有限规范记录结构的本地快照。不受支持的 JSON 结构以及 HTML/文本负载仍会明确标示为不支持，无法查询。

本地设置

此仓库使用 src/ 布局。uv sync --no-editable 会安装本地包，并通过 uv run --no-editable 提供 saudi-open-data-mcp 控制台脚本；本地命令无需手动设置 PYTHONPATH。

使用 uv 安装并同步：

uv sync --no-editable

然后，可以按下文所示使用 uv run --no-editable，也可以激活本地环境：

source .venv/bin/activate

或者从 .venv/bin/... 显式调用已安装的工具。

Lint：

uv run --no-editable ruff check .

测试：

uv run --no-editable pytest

本地运行

受支持的本地开发方式是通过 uv run --no-editable 运行本地控制台脚本：

uv run --no-editable saudi-open-data-mcp check-startup
uv run --no-editable saudi-open-data-mcp run-stdio
HTTP_AUTH_TOKEN="$(openssl rand -hex 32)" uv run --no-editable saudi-open-data-mcp run-http --host 127.0.0.1 --port 8000

激活 .venv 后，无需 uv run 即可使用相同的控制台脚本：

saudi-open-data-mcp check-startup
saudi-open-data-mcp run-stdio
HTTP_AUTH_TOKEN="$(openssl rand -hex 32)" saudi-open-data-mcp run-http --host 127.0.0.1 --port 8000

同一 CLI 还提供了一个精简的非交互式本地接口，用于执行当前核心操作。这些命令默认输出结构化 JSON，并支持使用 --output 写入文件。只有设置了 --output 时，--quiet 才会生效。读取、健康检查和配置命令的 --format 仍为 json；而 export 现在也支持对受治理的 query_dataset 结果生成 excel 和 pdf 文件：

uv run --no-editable saudi-open-data-mcp list
uv run --no-editable saudi-open-data-mcp query sama-pos-weekly --filter week_end_date=2024-01-13 --limit 5
uv run --no-editable saudi-open-data-mcp preview stats-gov-sa-cpi-headline-monthly
uv run --no-editable saudi-open-data-mcp download sama-money-supply-weekly
uv run --no-editable saudi-open-data-mcp export sama-money-supply-weekly --output money_supply.json
uv run --no-editable saudi-open-data-mcp export sama-money-supply-weekly --format excel --output money_supply.xml
uv run --no-editable saudi-open-data-mcp export sama-money-supply-weekly --format pdf --output money_supply.pdf
uv run --no-editable saudi-open-data-mcp health mof-budget-balance-quarterly
uv run --no-editable saudi-open-data-mcp refresh --dataset sama-money-supply-weekly
uv run --no-editable saudi-open-data-mcp refresh --include-optional
uv run --no-editable saudi-open-data-mcp config

Excel 文件是与 Excel 兼容的 XML 工作簿，包含可见的元数据和记录工作表。PDF 文件是以元数据为主的文本 PDF，会明确标示状态、来源、时效性和限制，而不会添加装饰性的报告层。

开发和本地主机集成时，请使用本地控制台脚本或辅助脚本。

对于 Claude Desktop 和其他基于命令的 MCP 主机，run-stdio 仍是主要的本地主机／操作员使用方式。

run-http 会通过可流式传输的 HTTP 启动同一应用。此方式仅适用于了解 MCP 且支持会话的场景。它适用于 MCP 检查器和 MCP 客户端，不适用于通用浏览器探测。现在必须使用 HTTP_AUTH_TOKEN 配置 Authorization: Bearer <token>，并使用 HTTP_AUTH_ROLE 明确指定 HTTP 角色。配置的角色会解析为允许的能力组合；HTTP_AUTH_CAPABILITIES 可以省略，也可以显式设置为相同的角色能力组合。

默认情况下，本地注册表和快照状态存储在仓库的 .local/ 目录下；设置 REGISTRY_PATH 或 SNAPSHOT_DIR 可显式覆盖这些路径。为确保主机运行可复现，建议显式设置 REGISTRY_PATH、SNAPSHOT_DIR、SAMA_BASE_URL 和 DATA_GOV_SA_BASE_URL。

本地状态说明：

• download_dataset 只报告本地快照存储中已有的内容，不会远程获取数据。
• 只有存在本地快照且规范化层能够从该快照导出规范记录时，query_dataset 才能运行。
• 如果不存在本地快照，download_dataset 会返回 artifact_missing，而 query_dataset 会返回 snapshot_missing。
• 在全新检出的代码库中，在配置的快照目录下写入快照之前，预期会出现这些仅限本地的状态。
• 公开的下载和健康检查输出会显示工件是否存在及其时效性证据，而不会暴露本地快照路径。
• 在有意义的情况下，核心工具结果会提供一致的顶层元数据，例如 data_origin、freshness_status、failure_stage 和 degradation_reason，以便更轻松地解读降级和失败路径。

本地 HTTP 开发仍可使用辅助脚本：

./scripts/run_local_http.sh

官方内部容器化服务

本阶段官方的内部服务方式是容器化的可流式传输 HTTP。

选定的服务模式：

• 基于 FastMCP 可流式传输 HTTP 的 run-http

选择此模式的原因：

• 为内部操作员提供单一的长时间运行服务形式
• 相比 stdio，更适合容器进程监控
• 保留本地已验证的相同 MCP 接口和工具语义

规范容器入口点为：

saudi-open-data-mcp run-http

该镜像设置了容器专用的运行时默认值：

• HTTP_HOST=0.0.0.0
• HTTP_PORT=8000
• 必须由操作员提供 HTTP_AUTH_TOKEN
• HTTP_AUTH_ROLE=operator
• HTTP_AUTH_CAPABILITIES=read,refresh,materialize
• TIER_A_REFRESH_ENABLED=false
• TIER_A_REFRESH_INTERVAL_SECONDS=3600
• REGISTRY_PATH=/var/lib/saudi-open-data-mcp/registry.sqlite
• SNAPSHOT_DIR=/var/lib/saudi-open-data-mcp/snapshots
• CACHE_DIR=/var/lib/saudi-open-data-mcp/cache

此运行时的持久化说明：

• 如果需要在替换后保留状态，REGISTRY_PATH 和 SNAPSHOT_DIR 应位于持久存储上
• CACHE_DIR 是可重新创建的临时空间
• 日志、resource://observability 计数器、内存中的速率限制和刷新循环状态均为进程本地数据

使用 Docker Compose 构建并运行服务：

docker compose up --build

提供的 compose 文件会将服务发布到主机上的 127.0.0.1:8000，将运行时状态持久化到挂载在 /var/lib/saudi-open-data-mcp 的 Docker 管理卷中，启用 init: true，并采用与镜像相同的 /startupz 启动探测契约。启动前，必须在运维人员的环境中设置 HTTP_AUTH_TOKEN。

内部可观测性仍有意保持简单：

• 读取 resource://observability，即可在一处检查当前按组归类的进程内计数器
• 检查结构化容器日志，获取事件级详情，例如 server.startup.*、preview.request.*、connector.request.*、materialize.* 和 tier_a_refresh.*
• 将可观测性资源视为进程本地的运维辅助工具，而非健康检查端点或外部指标 API

有关运维人员启动、关闭、刷新、备份和恢复的指导，请参阅 OPERATIONS.md。

直接运行容器的示例：

docker build -t saudi-open-data-mcp .
docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e HTTP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  -v saudi-open-data-mcp-data:/var/lib/saudi-open-data-mcp \
  saudi-open-data-mcp

容器/运行时要求：

• 启动时仍会执行注册表引导
• Tier A 后台刷新可用，但默认禁用
• 启用后，Tier A 刷新会在服务生命周期开始后立即运行，随后按配置的间隔重复执行
• 刷新仅复用现有的 Tier A 热集物化路径；此阶段不涉及 Tier B
• 单个数据集的刷新失败会明确记录在物化结果中，不会中止整个刷新循环
• 此阶段不会添加外部调度器或分布式刷新系统
• 最小化的 bearer-token 身份验证仅在 HTTP 路径上强制执行
• HTTP 角色仅在 HTTP 路径上强制执行：
  • viewer 可读取、查询元数据、检查健康状态、策略和可观测性
  • operator 拥有 viewer 的访问权限，另外还可使用 preview_dataset 和 materialize_hot_set
  • admin 是当前最高角色，拥有与 operator 相同的运维权限组合
• 当前角色权限组合在底层仍基于能力：
  • read 用于资源以及本地读取/查询/搜索工具
  • refresh 用于 preview_dataset
  • materialize 用于 materialize_hot_set
• 此阶段不声称已具备面向公共互联网部署的加固能力
• 如果需要在容器替换后保留注册表和快照状态，则应使用持久存储
• 面向运维人员的主要覆盖项包括 HTTP_AUTH_TOKEN、HTTP_AUTH_ROLE、HTTP_AUTH_CAPABILITIES、TIER_A_REFRESH_ENABLED、TIER_A_REFRESH_INTERVAL_SECONDS、SAMA_BASE_URL、DATA_GOV_SA_BASE_URL 和 LOG_LEVEL 当前配置仍将这些基础 URL 覆盖项明确限定为特定数据源，因为运行时仍带有 SAMA 特定假设以及 data.gov.sa 试点假设。

启动/就绪契约：

• 容器的任务是启动 MCP HTTP 服务并保持运行
• GET /startupz 是此阶段规范的机器可读启动探针
• GET /readyz 仍是同一启动专用负载的兼容别名
• /startupz 和 /readyz 仅表示：
  • 进程正在运行
  • 配置验证已通过
  • 运行时存储准备已通过
  • 核心 FastMCP 应用接线已完成
• 不包含有效 Authorization: Bearer <token> 标头的 HTTP 请求会被拒绝，并返回 401 Unauthorized
• 携带有效令牌但角色／能力不足的 HTTP 请求会被拒绝，并返回 403 Forbidden
• /startupz 和 /readyz 不代表：
  • 上游数据源可访问
  • 数据集是最新的
  • 连接器运行正常
  • 系统整体健康
• 如需验证实际会话是否就绪，必须使用支持 MCP 的客户端检查 /mcp
• 直接对 / 或 /mcp 进行简单的 GET 探测仍可能返回 404 或 406，这本身并不表示服务故障

精选实时金丝雀测试约定：

• uv run --no-editable saudi-open-data-mcp upstream-canary 会对以下数据执行实时连接器获取和规范化：
  • sama-exchange-rates-current
  • stats-gov-sa-cpi-headline-monthly
  • mof-budget-balance-quarterly
• 在注册可查询的 data.gov.sa 数据集之前，会跳过 data.gov.sa，并明确记录日志；仅目录试点数据集不会用作金丝雀测试目标。
• 金丝雀测试失败意味着某条精选且获准的路由在可访问性、响应结构或规范化行为方面发生变化，导致无法再生成预期的、可从记录推导的结果
• 金丝雀测试不代表目录已全面覆盖、数据集是最新的或连接器整体健康

MCP 主机注册

对于本地桌面 MCP 主机注册，请使用 stdio。对于基于命令的主机，这仍是受支持的开发／运维方式，与官方内部容器服务路径相互独立。

对于基于 stdio 的 MCP 主机，请使用带绝对路径的源码树 CLI。仓库中的 server.json 是此内部／评估版 alpha 的仓库级 MCP 元数据。在实际发布软件包之前，它会有意不声明 PyPI、npm 或 MCP 注册表软件包。

Claude Desktop 示例：

{
  "mcpServers": {
    "saudi-open-data-mcp": {
      "command": "/absolute/path/to/saudi-open-data-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/saudi-open-data-mcp/src/saudi_open_data_mcp/cli.py",
        "run-stdio"
      ],
      "cwd": "/absolute/path/to/saudi-open-data-mcp",
      "env": {
        "LOG_LEVEL": "ERROR",
        "SAMA_BASE_URL": "https://www.sama.gov.sa",
        "DATA_GOV_SA_BASE_URL": "https://open.data.gov.sa"
      }
    }
  }
}

此处的 cwd 可选。默认注册表和快照路径现在以仓库为基准，而非进程工作目录；不过，将 cwd 设为仓库根目录仍可让本地配置和路径的判断更简单。

安装软件包后，基于命令的主机也可以直接启动控制台脚本：

{
  "mcpServers": {
    "saudi-open-data-mcp": {
      "command": "saudi-open-data-mcp",
      "args": ["run-stdio"],
      "env": {
        "LOG_LEVEL": "ERROR",
        "SAMA_BASE_URL": "https://www.sama.gov.sa",
        "DATA_GOV_SA_BASE_URL": "https://open.data.gov.sa"
      }
    }
  }
}

如果你更倾向于使用单一命令路径，仓库还包含一个 stdio 辅助脚本：

{
  "mcpServers": {
    "saudi-open-data-mcp": {
      "command": "/absolute/path/to/saudi-open-data-mcp/scripts/run_local_stdio.sh"
    }
  }
}

请明确当前限制：本地 MCP 主机仍通过源码树 CLI 使用 stdio 注册。官方容器服务路径使用 HTTP，并非桌面 stdio 主机的替代方案。

使用 MCP Inspector 手动测试

HTTP 是官方的内部容器服务模式，但它并非普通的 REST 接口。/mcp 是 MCP 端点，不是普通的浏览器页面。

1. 在一个终端窗口中启动 HTTP MCP 服务：

export HTTP_AUTH_TOKEN="$(openssl rand -hex 32)"
uv run --no-editable saudi-open-data-mcp run-http --host 127.0.0.1 --port 8000

2. 在另一个终端窗口中检查启动探针：

curl -s http://127.0.0.1:8000/startupz

3. 在 MCP Inspector 中，连接到 Streamable HTTP URL http://127.0.0.1:8000/mcp。
4. 如果已启用身份验证，请添加 Authorization: Bearer <the value of HTTP_AUTH_TOKEN>。
5. 尝试安全的调用，例如 resource://catalog、search_datasets({"query": "money"})、dataset_metadata({"dataset_id": "sama-money-supply-weekly"}) 和 dataset_health({"dataset_id": "sama-money-supply-weekly"})。

即使服务运行正常，简单的探测也可能看起来像是出了问题：

• GET / 可能返回 404
• GET /mcp 如果没有预期的 MCP 标头，可能会返回 406，这是预期行为
• GET /startupz 是健康状态／启动探针，应返回 200，并附带范围有限、仅用于启动检查的负载

对于当前的流式 HTTP 设置，这是预期行为。在这里，浏览器或 curl 检查仅适用于负向冒烟测试，不能作为真正的 MCP 会话测试。

支持 MCP 的程序化测试示例：

import asyncio
import os

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport


async def main() -> None:
    async with Client(
        transport=StreamableHttpTransport(
            "http://127.0.0.1:8000/mcp",
            headers={"Authorization": f"Bearer {os.environ['HTTP_AUTH_TOKEN']}"},
        )
    ) as client:
        result = await client.call_tool(
            "dataset_metadata",
            {"dataset_id": "sama-money-supply-weekly"},
        )
        print(result.structured_content)


asyncio.run(main())

测试

该代码库包含四层测试：

• tests/unit/：类型化契约、工具行为、仓库行为、连接器行为和规范化行为
• tests/integration/：小规模跨模块组合检查
• tests/contracts/：架构边界检查，包括工具模块不得直接导入连接器这一规则
• tests/smoke/：基本 CLI／可导入性验证

代码库结构

主要代码位于 src/saudi_open_data_mcp/ 下。

• connectors/：数据源访问契约和各数据源连接器（SAMA、stats.gov.sa、MoF、data.gov.sa）
• normalization/：字段映射、验证器、管道和最小化规范记录
• registry/：类型化元数据模型、SQLite 仓库和引导程序
• storage/：快照和本地数据新鲜度辅助工具
• resources/：由注册表提供支持的 MCP 资源
• tools/：由注册表提供支持的 MCP 工具和仅限本地的 MCP 工具，以及通过连接器路径进行的预览
• observability/：结构化日志记录、进程内计数器、上游金丝雀检查
• security/：HTTP 身份验证中间件、就绪探针、速率限制、输入清理
• config.py：运行时配置和环境变量解析
• cli.py：基于 MCP 核心的轻量级非交互式 CLI
• server.py：FastMCP 组装
• docs/：架构、ADR、路线图和数据集说明

路线图／后续步骤

近期工作应与当前架构保持一致：

• 强化当前 MCP 接口，并确保其描述、契约和身份处理保持一致
• 仅在数据源结构能够安全支持更丰富的规范记录时，才深入完善规范化层
• 改进打包、本地运行体验，以及围绕当前 FastMCP 服务的发布呈现
• 继续强化可靠性和可观测性
• 只有在 SAMA 路径和注册表契约稳定后，才添加第二个数据源