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 根据需要。

环境变量

环境变量被读入 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平台的详细信息，请参阅上面链接的官方文档。