AI导哈

开放数据MCP服务器

Schwaizer OpenData MCP服务器提供对瑞士开放数据门户(opendata.swiss)的只读访问，通过安全的MCP工具映射CKAN的公共Action API，适用于数据查询和管理场景。

  • by ishumilin
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 ishumilin/schwaizer-opendata-mcp

使用说明

Schwaizer

MCP Server: OpenData MCP

An unofficial MCP server for interacting with Switzerland's open data portal (opendata.swiss, CKAN).

This is a community project by Schwaizer and is not an official implementation by the Swiss government.

关于Schwaizer

塑造瑞士人工智能的未来

通过负责任的人工智能采用，赋予瑞士企业和社会权力。

Schwaizer成立于2025年，是一家非营利组织，致力于在瑞士加速负责任地采用人工智能。

网站：https://www.schwaizer.ch

概述

Schwaizer OpenData MCP服务器提供对瑞士开放数据门户（OpenData.Swiss）的只读访问，该门户由CKAN提供支持。服务器公开安全、经过验证的MCP工具，这些工具映射到CKAN的公共Action API：数据集搜索/显示、组织/组/标签、资源/视图和数据存储查询。为了性能和安全，强制执行限制和合理的默认值。

特性

  • 核心CKAN行动的MCP工具：
    • 目录
      • package_search --使用方面、分页、排序搜索数据集
      • package_show --按id/name获取数据集
    • 组织/团体/标签
      • organization_list, organization_show
      • group_list, group_show
      • tag_list, tag_autocomplete
    • 资源和视图
      • resource_show, resource_view_show
    • 数据存储
      • datastore_info
      • datastore_search --具有安全默认值和防御限制的GET/POST
      • datastore_search_sql --默认情况下禁用（由配置保护）
    • 状态/帮助
      • status_show
      • help_show
  • 安全和性能护栏：
    • 服务器端通过以下方式限制行数 MAX_ROWS / DEFAULT_ROWS
    • include_total 默认为false以避免昂贵的计数
    • datastore_search_sql 默认禁用；受DDL/DML保护
  • 使用Zod进行输入验证（模式导出为JSON模式供工具使用）
  • 基于ky的HTTP客户端，具有合理的超时和通过pino进行结构化日志记录

安装

先决条件

  • Node.js 20.0.0或更高版本
  • npm或pnpm

再进行

npm install

配置

复制示例环境文件：

cp .env.example .env

然后调整中的值 .env 根据需要。

环境变量

名称 默认值 描述
BASE_URL https://opendata.swiss/api/3/action CKAN操作API基本URL（无尾部斜线）。
ENABLE_SQL false 启用 datastore_search_sql。出于安全考虑，默认禁用。
TIMEOUT_MS 15000 HTTP客户端超时（毫秒）。
USER_AGENT schwaizer-opendata-mcp/0.1.0 (+https://opendata.swiss) 发送到CKAN API的User‑Agent头。
MAX_ROWS 1000 服务器允许行数/限制参数的绝对上限。
DEFAULT_ROWS 25 客户端未指定值时的默认行数/限制。

环境变量被读入 src/config.js.

用法

通过stdio运行服务器：

# Production mode
npm start

# Development mode (auto-reload)
npm run dev

此MCP服务器通过stdio进行通信。配置启用MCP的客户端/工具以生成命令（例如。， node src/index.js 或包裹箱）并通过stdio连接。
该软件包还安装了一个bin：

"bin": { "schwaizer-opendata-mcp": "src/index.js" }

因此，您可以运行：

schwaizer-opendata-mcp

可用工具

  • 目录
    • package_search （参数： q, fq, sort, rows, start, facetField, facetLimit, includeTotal)
    • package_show （参数： id)
  • 组织/团体/标签
    • organization_list （参数： all_fields, limit, offset)
    • organization_show （参数： id)
    • group_list （参数： order_by, limit, offset, all_fields)
    • group_show （参数： id)
    • tag_list （参数： query)
    • tag_autocomplete （参数： q, limit)
  • 资源和视图
    • resource_show （参数： id)
    • resource_view_show （参数： id)
  • 数据存储
    • datastore_info （参数： id, include_private)
    • datastore_search （参数： resource_id, q, filters, fields, sort, language, include_total, limit, offset, distinct, plain, full_text)
    • datastore_search_sql （参数： sql)--需要 ENABLE_SQL=true
  • 状态/帮助
    • status_show （无参数）
    • help_show （参数： name)

API 文档

  • CKAN Action API 数据库 (opendata.swiss): https://opendata.swiss/api/3/action
  • CKAN API参考：https://docs.ckan.org/en/latest/api/index.html

集成测试

集成测试对opendata.swiss进行真正的API调用，以验证MCP服务器与活动CKAN实例是否正常工作。这些测试：

  • 使用真正的API调用（无模拟）来测试实际行为
  • 遵守速率限制，测试之间的延迟很小
  • 使用已知数据集中的稳定测试数据（如BFS统计数据）
  • 优雅地处理不可用的功能（例如，禁用SQL搜索，没有数据存储资源）
  • 对于网络访问受限的CI/CD环境，可以通过环境变量禁用

运行集成测试

# Run integration tests
npm run test:integration

# Skip integration tests (useful in CI/CD)
SKIP_INTEGRATION_TESTS=true npm test

# Run with verbose output
npm run test:integration -- --reporter=verbose

集成测试覆盖率

  • 目录 (tests/integration/catalog.integration.test.js)：使用过滤器/分页/排序、数据集检索、列表/自动补全、活动提要进行搜索
  • 数据存储 (tests/integration/datastore.integration.test.js)：信息/搜索、字段/排序、SQL（如果启用）、资源的动态发现
  • 资源 (tests/integration/resources.integration.test.js)：资源元数据和视图
  • 组织/分类 (tests/integration/org-taxonomy.integration.test.js)：组织、组、标签、词汇表和许可证、自动补全
  • 状态 (tests/integration/status.integration.test.js)：平台状态和API帮助

发展

项目结构

schwaizer-opendata-mcp/
├── src/
│   ├── index.js              # MCP server entry (stdio)
│   ├── config.js             # Configuration loader (.env)
│   ├── api/
│   │   └── ckan-client.js    # CKAN HTTP client
│   ├── tools/                # MCP tool handlers
│   │   ├── catalog.js
│   │   ├── org-taxonomy.js
│   │   ├── resources.js
│   │   ├── datastore.js
│   │   └── status.js
│   └── utils/
│       └── logger.js         # pino logger
├── tests/
│   ├── unit/
│   └── integration/
├── docs/
├── .env.example
└── package.json

脚本

  • npm start --启动MCP服务器
  • npm run dev --从文件更改时自动重新加载开始
  • npm test --运行所有测试
  • npm run test:unit --运行单元测试
  • npm run test:integration --运行集成测试
  • npm run test:watch --测试的监视模式
  • npm run test:coverage --生成覆盖率报告
  • npm run lint --运行ESLint
  • npm run format --带Prettier的格式
  • npm run docs -使用JSDoc构建API文档（目的地： docs/)

缓存

默认情况下，服务器不实现缓存。所有请求都直接转发到opendata.swiss上的CKAN API。如果您的用例需要，请考虑实现客户端缓存。

错误处理

服务器提供全面的错误处理：

  • 输入验证：在进行API调用之前，使用Zod模式验证所有工具输入
  • API错误：捕获CKAN API错误并返回描述性消息
  • 速率限制：服务器遵守CKAN的速率限制；如果需要，考虑在请求之间增加延迟
  • 超时处理：可配置的超时（默认15秒）可防止挂起请求
  • SQL安全: datastore_search_sql 默认情况下禁用，启用时包括DDL/DML保护

常见错误场景：

  • 404未找到：数据集或资源不存在
  • 400错误请求：查询参数或筛选器无效
  • 403禁止：访问被拒绝（公共API很少访问）
  • 500服务器错误：CKAN平台问题
  • 超时：请求已超出 TIMEOUT_MS 限制

典型工作流程

1.搜索数据集

首先搜索与您的主题相关的数据集：

// Search for datasets about education
package_search({
  "q": "education",
  "fq": "organization:bundesamt-fur-statistik-bfs",
  "rows": 10
})

2.获取数据集详细信息

找到相关数据集后，获取其全部详细信息：

// Get complete dataset information
package_show({
  "id": "bildungsabschlusse"
})

3.探索数据存储资源

检查数据集是否具有启用数据存储的资源：

// Get datastore info for a resource
datastore_info({
  "id": "resource-id-from-package-show"
})

4.查询数据

最后，使用过滤器查询实际数据：

// Search datastore with filters
datastore_search({
  "resource_id": "resource-id",
  "filters": {
    "Jahr": "2023",
    "Kanton": "ZH"
  },
  "limit": 100
})

贡献

欢迎投稿！请打开问题或提交拉取请求。

许可证

MIT许可证——见 LICENSE.

支持

对于此MCP服务器的问题，请在项目的GitHub存储库上打开问题。
有关CKAN/opendata.swiss平台的详细信息，请参阅上面链接的官方文档。

相关 MCP