KSA开放数据MCP🇸🇦

国家级、只读MCP服务器，用于沙特开放数据目录访问+允许列出的部委/当局API集成，带有FastAPI网关和内置向量内存。

______________________________________________________________________

👑 项目领导力

阿里·戈奈姆 --塑造国家方向的远见者和战略家。\

领英： https://www.linkedin.com/in/alighnaim/

哈龙·沙夫卡特 --项目负责人和将这一倡议变为现实的人。\

领英： https://www.linkedin.com/in/haroon-shafqat/\ 网站： https://www.hwah.net

______________________________________________________________________

📚 目录

1）这个项目是什么
2）为什么存在此MCP
3）核心能力
4）端到端架构
5）运行时URL映射
6）一个命令启动
7） FastAPI网关合同
8） MCP工具参考（所有工具）
9）源允许列表（国家连接器）
10）内置矢量存储器
11） CKAN弹性模式
12）安全和授权姿势
13）质量门和测试
14）正式烟雾证据
15）存储库结构
16）贡献者工作流
17）路线图和操作说明
18）治理文件
19）许可证

______________________________________________________________________

1）这个项目是什么

ksa-opendata-mcp 是一款以沙特为重点的MCP服务器，设计用于：

公共数据集的统一发现，
从已分配的源API中安全检索，
用于代理集成的确定性工具契约，
使用Docker和FastAPI的生产友好运行时。

这是故意的只读，明确分配，并设计用于与AI代理和开发工具（Cursor、ChatGPT应用程序、自定义MCP客户端）的互操作性。

______________________________________________________________________

2）为什么存在此MCP

政府和公民数据消费者需要一个可靠的集成点，而不是几十个不兼容的源API和数据门户。本项目通过以下方式对其进行标准化：

稳定的MCP工具表面，
严格的源代码管理(sources.yaml),
可审计的运行时行为，
双语和阿拉伯语感知检索支持，
透明的操作文档。

______________________________________________________________________

3）核心能力

✅ 协议和API访问

本地MCP流式HTTP端点(/mcp/).
FastAPI包装器(/api/*, /docs, /openapi.json).
健康监测端点(/health).

✅ 国家来源整合

CKAN目录集成（沙特开放数据平台）。
REST和API-key保护的权威机构连接器。
端点级分配和主机控制。

✅ 安全数据处理

有界预览（行/大小限制）。
设计只读行为。
没有回写工具。

✅ 运行时内存

PostgreSQL+ pgvector 语义记忆层。
轻量级的阿拉伯语友好嵌入策略。
透明 memory_search 召回工具。

✅ 交付人体工程学

一个命令启动脚本： ./ksa-mcp.sh.
Docker化应用+Postgres。
自动生成的游标和ChatGPT设置文件。

______________________________________________________________________

4）端到端架构

flowchart LR
    A[MCP Clients] --> B[FastAPI Wrapper]
    B --> C[MCP Streamable HTTP App]
    C --> D[Tool Layer]
    D --> E[Source Registry]
    D --> F[CKAN Services]
    D --> G[REST Adapter]
    D --> H[Preview Service]
    D --> I[Ranking Service]
    D --> J[Vector Memory Service]
    J --> K[(Postgres + pgvector)]
    E --> L[sources.yaml]
    F --> M[open.data.gov.sa]
    G --> N[Ministry and Authority APIs]

运行时组件

server.py：MCP工具声明和编排。
fastapi_app.py：FastAPI API网关+安装的MCP传输应用程序。
**ksa_opendata/services/***：目录/数据存储/预览/排名/内存服务。
docker-compose.yml：应用程序+Postgres(pgvector/pgvector:pg16).

______________________________________________________________________

5）运行时URL映射

主要本地主机

基本URL: http://ksa-opendata-mcp.localhost:8000

人/API终点

健康： http://ksa-opendata-mcp.localhost:8000/health
OpenAPI架构： http://ksa-opendata-mcp.localhost:8000/openapi.json
Swagger文档： http://ksa-opendata-mcp.localhost:8000/docs
重新记录： http://ksa-opendata-mcp.localhost:8000/redoc

MCP端点

MCP可流式传输HTTP： http://ksa-opendata-mcp.localhost:8000/mcp/

FastAPI工具网关

工具列表： http://ksa-opendata-mcp.localhost:8000/api/tools
工具调用： http://ksa-opendata-mcp.localhost:8000/api/tools/{tool_name}
欢迎元数据： http://ksa-opendata-mcp.localhost:8000/api/welcome

静态资产

图标URL: http://ksa-opendata-mcp.localhost:8000/assets/ksa-mcp-icon-128.jpg

集装箱网络等效物

MCP： http://ksa-opendata-mcp:8000/mcp/
工具API： http://ksa-opendata-mcp:8000/api/tools

______________________________________________________________________

6）一个命令启动

./ksa-mcp.sh

创业公司做什么

验证Docker的可用性，
确保 .env 存在（如果缺失，则自动创建默认值），
重新生成本地连接配置文件：

- .cursor/mcp.json - reports/chatgpt_mcp_setup.json

构建/启动app+Postgres，
运行健康检查和API烟雾检查，
打印工具清单和运行时URL。

作战命令

./ksa-mcp.sh help
./ksa-mcp.sh status
./ksa-mcp.sh logs
./ksa-mcp.sh stop
./ksa-mcp.sh rebuild
./ksa-mcp.sh configure

______________________________________________________________________

7） FastAPI网关合同

认证行为

被控制 MCP_API_KEY_REQUIRED.
此存储库中的默认值： false （公共模式）。
启用后，客户端发送： X-API-Key: .

主要终点

GET /health\

运行时和内存就绪。

GET /api/welcome\

部署元数据和集成提示。

GET /api/tools\

MCP工具列表。

POST /api/tools/{tool_name}\

使用JSON主体参数调用任何MCP工具。

POST/GET /mcp/\

可流式传输MCP传输端点。

______________________________________________________________________

8） MCP工具参考（所有工具）

工具	目的	典型输入	典型输出
`list_sources()`	列出已配置的连接器	无	源元数据列表
`list_publishers(...)`	列出目录发布者	`source_id`, `query`, `limit`	出版商列表
`search_datasets(...)`	搜索和排名数据集	`query`, `publisher`, `rows`, `start`	数据集列表+排名
`get_dataset(...)`	获取标准化数据集详细信息	`dataset_id_or_name`	数据集元数据+资源
`get_resource(...)`	获取规范化的资源元数据	`resource_id`	资源元数据
`preview_resource(...)`	安全资源内容预览	`resource_id` 或 `url`, `rows`, `max_bytes`	有界预览有效载荷
`publisher_summary(...)`	出版商简介摘要	`publisher`, `sample_rows`	顶级格式/标签+计数
`datastore_search(...)`	查询CKAN数据存储形状	`resource_id`, `filters`, `limit`, `offset`	记录+字段模式
`call_source_endpoint(...)`	调用已分配的REST端点	`source_id`, `endpoint`, `params`	原始源有效载荷
`memory_search(...)`	基于先前工具响应的语义搜索	`query`, `limit`	排名记忆匹配

示例（FastAPI工具调用）

curl -sS -X POST "http://ksa-opendata-mcp.localhost:8000/api/tools/call_source_endpoint" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "moh_hdp_api",
    "endpoint": "dataset_search_public",
    "params": {
      "search": "الصحة",
      "pageNumber": 1,
      "pageSize": 2
    }
  }'

______________________________________________________________________

9）源允许列表（国家连接器）

配置于 sources.yaml.

源ID	类型	基本URL
`ksa_open_data_platform`	`ckan`	`https://open.data.gov.sa`
`shc_open_data_apis`	`rest`	`https://services.shc.gov.sa/CouncilAPIs/api/CouncilAPIs`
`moh_hdp_api`	`rest`	`https://hdp.moh.gov.sa/api/v1`
`mcit_open_api`	`rest_api_key`	`https://api.mcit.gov.sa`
`sama_open_data_api`	`rest`	`https://data.sama.gov.sa`
`cchi_odata`	`rest`	`https://opendata.cchi.gov.sa/odata`
`gastat_api`	`rest`	`https://api.stats.gov.sa`

只有每个源显式声明的端点是可调用的。

______________________________________________________________________

10）内置矢量存储器

它的作用

在PostgreSQL中缓存工具响应。
存储用于语义查找的嵌入向量。
通过以下方式公开检索 memory_search.

为什么这个设计

计算开销非常低。
适用于阿拉伯语/英语混合有效载荷。
提高重复查询性能和连续性。

主要配置键

VECTOR_MEMORY_ENABLED
VECTOR_MEMORY_TTL_SECONDS
VECTOR_MEMORY_MAX_TEXT_CHARS
EMBEDDING_MODEL_NAME （默认本地轻量级配置文件）
EMBEDDING_DIM
DATABASE_URL

______________________________________________________________________

11） CKAN弹性模式

当CKAN上游被阻止或在给定网络中返回非JSON WAF页面时，目录工具会使用本地可用的部委/实体元数据自动降级为确定性回退模式。

这保持了：

工具收缩稳定，
MCP呼叫成功，
贡献者工作流已解除阻塞。

后备保障范围包括：

list_publishers
search_datasets
get_dataset
get_resource
publisher_summary
datastore_search

______________________________________________________________________

12）安全和授权姿势

基线保障措施

只读工具。
明确的排外主义者来自 sources.yaml.
主机检查出站URL。
响应/预览界限。
对工具调用进行审核日志记录。

身份验证控件

展示/开发人员入职支持公共模式。
API密钥模式可用于强化部署。

环境变量

变量	目的
`FASTAPI_API_KEY`	启用身份验证时使用的API密钥
`MCP_API_KEY_REQUIRED`	切换身份验证要求
`MCP_PUBLIC_BASE_URL`	生成的元数据/设置中使用的URL
`MCP_SERVER_NAME`	显示器/服务器名称
`MCP_SERVER_DESCRIPTION`	面向集成的描述
`MCP_ICON_URL`	面向集成的图标URL
`MCIT_API_KEY`	MCIT连接器的源身份验证密钥
`POSTGRES_DB` / `POSTGRES_USER` / `POSTGRES_PASSWORD`	DB凭据
`DATABASE_URL`	Postgres连接字符串

______________________________________________________________________

13）质量门和测试

静态+动态验证

ruff check .
PYTHONPATH=. mypy ksa_opendata server.py fastapi_app.py
PYTHONPATH=. pytest

此仓库中的最新基线：

ruff：通过
mypy （应用范围）：通过
pytest：通过

______________________________________________________________________

14）正式烟雾证据

最新的正式工具烟雾工件：

reports/smoke_tool_report.md
reports/smoke_tool_report.json

这些措施包括：

从MCP现场发现完整的工具库存，
每个工具的调用参数，
每个工具的通过/失败状态，
关键证据片段（计数、ID、样本名称），
实时源获取证明(moh_hdp_api).

其他证据人工制品：

reports/fetch_validation_report.md
reports/fetch_validation_report.json
reports/govsa_entity_registry.json
reports/govsa_ministries_registry.json
reports/govsa_entity_registry.md

______________________________________________________________________

15）存储库结构

.
├── server.py                         # MCP tools and orchestration
├── fastapi_app.py                    # FastAPI wrapper + mounted MCP app
├── docker-compose.yml                # app + postgres services
├── Dockerfile                        # container build
├── ksa-mcp.sh                        # one-command startup UX
├── sources.yaml                      # source/endpoint allowlist
├── ksa_opendata/
│   ├── config.py
│   ├── registry.py
│   ├── sources/
│   └── services/
├── contrib/                          # national entity/ministry scaffolds
├── docs/                             # architecture, API, security docs
├── tests/                            # unit + integration tests
└── reports/                          # generated validation artifacts

______________________________________________________________________

16）贡献者工作流

启动堆栈： ./ksa-mcp.sh
确认健康状况： ./ksa-mcp.sh status
在中选择一个实体/部委积压文件 contrib/
添加源映射/端点集成
添加单元/集成测试
运行质量闸门
根据需要更新报告/文档

______________________________________________________________________

17）路线图和操作说明

计划硬化路径

稳定的公共域+TLS前端，
可选OAuth（如果部署模型需要），
扩展了特定部委的端点包，
更丰富的查询/排名语义，
所有MCP工具的CI烟雾自动化。

运行记录

外部源行为可能因网络/WAF状态而异。该存储库包括弹性逻辑和透明报告，因此行为保持确定性和可审计性。

______________________________________________________________________

18）治理文件

______________________________________________________________________

19）许可证

麻省理工学院（见 pyproject.toml).

______________________________________________________________________

制作❤️ 由胡伦和阿里撰写。

Ks Amcp

快速接入

详细介绍

KSA开放数据MCP🇸🇦

👑 项目领导力

📚 目录

1） 这个项目是什么

2） 为什么存在此MCP

3） 核心能力

✅ 协议和API访问

✅ 国家来源整合

✅ 安全数据处理

✅ 运行时内存

✅ 交付人体工程学

4） 端到端架构

运行时组件

5） 运行时URL映射

主要本地主机

人/API终点

MCP端点

FastAPI工具网关

静态资产

集装箱网络等效物

6） 一个命令启动

创业公司做什么

作战命令

7） FastAPI网关合同

认证行为

主要终点

8） MCP工具参考（所有工具）

示例（FastAPI工具调用）

9） 源允许列表（国家连接器）

10） 内置矢量存储器

它的作用

为什么这个设计

主要配置键

11） CKAN弹性模式

12） 安全和授权姿势

基线保障措施

身份验证控件

环境变量

13） 质量门和测试

静态+动态验证

14） 正式烟雾证据

15） 存储库结构

16） 贡献者工作流

17） 路线图和操作说明

计划硬化路径

运行记录

18） 治理文件

19） 许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1）这个项目是什么

2）为什么存在此MCP

3）核心能力

4）端到端架构

5）运行时URL映射

6）一个命令启动

9）源允许列表（国家连接器）

10）内置矢量存储器

12）安全和授权姿势

13）质量门和测试

14）正式烟雾证据

15）存储库结构

16）贡献者工作流

17）路线图和操作说明

18）治理文件

19）许可证