Ks Amcp

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: ``

集装箱网络等效物

• 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工具参考（所有工具）

示例（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.

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

______________________________________________________________________

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密钥模式可用于强化部署。

环境变量

______________________________________________________________________

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） 贡献者工作流

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

______________________________________________________________________

17） 路线图和操作说明

计划硬化路径

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

运行记录

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

______________________________________________________________________

18） 治理文件

• 贡献指南
• 行为准则
• 安全策略
• 文档索引
• 建筑
• API完整参考
• 实体登记文件

______________________________________________________________________

19） 许可证

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

______________________________________________________________________

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