i14y-mcp

属于 瑞士公共数据 MCP 组合 — 这是一个开源 MCP 服务集合，可将 AI Agent 连接到瑞士公共数据和开放数据。 这是一个私人项目，与任何雇主或公共机构均无关联，未获其认可，也不代表其运营。

i14y-mcp

面向 I14Y 互操作平台的 MCP 服务——瑞士国家元数据目录。

🇩🇪 德语版本

---

为什么需要这个服务

这个组合中的其他服务回答的是 «数据说明了什么？»。 而这个服务回答的是更先要弄清的问题：«谁发布这个主题的数据、通过什么接口提供、采用什么许可？»

I14Y 是由联邦统计局维护的国家数据目录。它使用 DCAT-AP-CH 配置文件（eCH-0200），描述联邦、州和市镇的数据集、已注册的 API、公共服务及统一概念。

记忆口诀：«先看目录，再找货架。» 没有目录，Agent 必须事先知道某个数据源的存在。有了目录，它就能找到数据源。

---

🎯 锚点演示查询

«哪个机构发布特殊教育需求相关数据？这些数据通过什么接口提供？采用什么许可？»

search_catalog(query="Sonderpädagogik")
  → «Statistik der Sonderpädagogik» — Federal Statistical Office (BFS), theme: Bildung

get_dataset(dataset_id=...)
  → 2 distributions, licence: «Opendata BY ASK — attribution required,
    commercial use only with permission from the data supplier»
  → contact: [email protected]

只需调用两个工具，就能把一个模糊的主题转化为明确的机构、下载 URL 和可据此采取行动的许可——get_dataset 会将分发信息、许可和联系点汇总到一条记录中。

演示

---

架构

                 ┌──────────────────────────────┐
                 │      MCP Host (Claude)       │
                 └───────────────┬──────────────┘
                                 │ stdio | streamable-http
                 ┌───────────────▼──────────────┐
                 │          i14y-mcp            │
                 │  ┌────────────────────────┐  │
                 │  │ server.py  (13 tools)  │  │
                 │  ├────────────────────────┤  │
                 │  │ mappers.py             │  │  DCAT → flat, one language
                 │  ├────────────────────────┤  │
                 │  │ models.py  (Pydantic)  │  │  source + provenance envelope
                 │  ├────────────────────────┤  │
                 │  │ client.py              │  │  retry 2s/4s/8s, no-retry 4xx
                 │  └────────────────────────┘  │
                 └───────────────┬──────────────┘
                                 │ HTTPS, no auth
                 ┌───────────────▼──────────────┐
                 │  api.i14y.admin.ch/api       │
                 │  datasets · dataservices ·   │
                 │  concepts · publicservices · │
                 │  catalogs · agents · search  │
                 └──────────────────────────────┘

架构决策

此服务采用架构 A（仅实时 API）。

理由（已于 2026-07-21 通过实时验证）：

• 所有读取端点均可在无需身份验证的情况下响应，并能正确分页。
• 不提供目录元数据的批量下载，也不需要此功能。
• 错误响应遵循 RFC 7807，因此可以区分不同的故障模式。

影响：

• 每次 HTTP 调用遇到暂时性故障时，都会按 2 秒 / 4 秒 / 8 秒的间隔重试。
• 由于上游忽略分页，search_catalog 会在客户端限制结果数量。
• api_status 始终返回可评估的状态，而不是空记录。

完整探测报告：docs/probe-i14y.md。

项目阶段

此服务处于该组合「只读优先」阶段架构的第 1 阶段（只读）：所有工具均为只读，没有身份验证，也不涉及个人数据。阶段模型以及未来启用写入能力的前提条件，请参阅 docs/roadmap.md。

---

工具

工具	用途
search_catalog	在目录中进行全文搜索。入口工具。
list_datasets	分页列出数据集注册表（完整，不同于搜索结果）。
get_dataset	获取单个数据集的完整元数据记录。
get_dataset_distributions	获取下载 URL、格式和许可。
list_data_services	列出瑞士官方 API 注册表及其端点 URL。
get_data_service	获取单个已注册接口的完整记录。
list_public_services	列出面向公民的行政服务。
list_concepts	列出统一概念和代码列表。
get_concept	获取单个概念定义。
search_codelist_entries	搜索代码列表中的单个代码。
list_publishers	列出发布机构及其瑞士 UID。
list_catalogs	列出参与的目录。
api_status	检查可访问性，并在出现问题时优雅降级。

所有工具均标注为 readOnlyHint: true。上游 API 支持写入操作，但本服务有意不对外提供这些操作。

MCP 基元

此服务仅提供工具——没有资源，也没有提示词。这是经过深思熟虑的选择，并非遗漏：I14Y 通过自由文本搜索和不透明 UUID 查询，因此没有一组小而稳定、可寻址的 URI 能够与 MCP 资源清晰对应；该服务也不附带主观性较强的提示词模板。每个工具都是只读且幂等的；如果未来出现稳定的入口（例如固定的主题列表），则可考虑将其作为资源。

---

MCP 协议版本

此服务在同一端点上支持两个协议时代。客户端在连接上的第一个请求决定适用哪个时代；之后若声称属于另一个时代，则会被拒绝。

时代	修订版本	适用对象
initialize 握手	2024-11-05 … 2025-11-25	当前客户端使用的版本。服务会返回请求中指定的修订版本；如果请求的是更新版本，则返回上限 2025-11-25。
逐请求信封	2026-07-28	携带 2026-07-28 _meta 信封的请求会开启现代连接。

这两个修订版本都固定在 tests/test_protocol_version.py 中，并与已安装的 SDK 进行断言比对，因此 Dependabot 对 mcp 的升级不会悄然改变任一版本。握手上限是通过组装好的 ASGI 堆栈执行实时 initialize 请求来测定的，而非从常量名称读取。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而非握手时代的别名——若仅以它为基准固定版本，当前客户端实际协商的时代就可能发生漂移。

现代修订版中服务所承载的内容

2026-07-28 将发现机制从 initialize 握手迁移到 server/discover 和按请求提供的 _meta 信封，并为每个可缓存结果提供新鲜度提示。此服务在这些接口上提供的内容，通过组装后的技术栈在 tests/test_spec_2026_07_28.py 中进行测量；对于 stdio，还会通过真实的子进程进行测量，而不是从配置中读取：

接口	此服务的响应内容
serverInfo，写入每个现代响应	名称、显示标题、描述、网站和已安装的发行版版本——与出站 User-Agent 携带的版本相同
server/discover → instructions	工具的调用顺序，以及 I14Y 中任一工具描述都无法单独展示的两个属性
ttlMs / cacheScope	此服务所响应的全部五种可缓存方法均为 300 s、public
tools[].title	每个工具的显示名称，以便客户端显示「搜索概念的代码列表」，而不是 search_codelist_entries

新鲜度提示并非装饰。如果没有设置，SDK 会返回 ttlMs: 0, cacheScope: private——「已过期，绝不共享」——即使目录在导入时就已固定，且进程运行期间无法更改。

两种传输方式都支持现代修订版：HTTP 通过流式 HTTP 会话管理器提供，stdio（默认方式，也是 uvx i14y-mcp 的启动方式）则通过同一个双时代循环提供。任何一种都不能作为另一种的依据，因此两者都要进行测量。

此服务会声明但不会使用的一项能力。 在 2026-07-28 中，listChanged 标志和 resources.subscribe 仅取决于是否提供 subscriptions/listen，而 SDK 会无条件接入该处理程序。因此，对于导入时就固定的工具列表，server/discover 会报告 listChanged: true；对于空资源列表，也会报告订阅能力；但实际上不会发送任何变更通知。无法通过公共 API 关闭此功能——只有彻底替换 server/discover 处理程序才能做到，但那会导致我们自身的能力出现第二种说法——因此我们通过测试固定这一行为，而不是掩盖问题。

更新策略。 门禁检查失败时，不要盲目修改常量：阅读两个修订版之间的规范更新日志，确认服务仍按预期运行，然后一起更新常量、本节、README.de.md 和 CHANGELOG.md。

---

安装

uvx i14y-mcp

或从源码安装：

git clone https://github.com/malkreide/i14y-mcp
cd i14y-mcp
pip install -e ".[dev]"

Claude Desktop

{
  "mcpServers": {
    "i14y": {
      "command": "uvx",
      "args": ["i14y-mcp"]
    }
  }
}

远程部署（Render、Railway）

I14Y_MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 i14y-mcp

I14Y_MCP_TRANSPORT 可接受 stdio（入口自身的默认值）、streamable-http（http 是其同义词）或 sse。HTTP 传输方式绑定到 HOST，其默认值为 127.0.0.1（环回地址）；在 PaaS 上设置 HOST=0.0.0.0 以公开端口（容器映像已同时完成这两项设置）。

连接器 URL：https://<host>/mcp

Claude.ai 自定义连接器使用流式 HTTP，而该传输方式仅提供一个路径：/mcp。sse 是较旧的传输方式，提供的是 /sse 和 /messages；通过组装后的应用进行测量可知，POST /mcp 在此方式下返回 404，而在流式 HTTP 下返回 200。因此，容器映像默认使用 streamable-http；若连接器指向 SSE 部署，则会收到 404，无法完成握手。

I14Y_MCP_ALLOWED_HOSTS — 公共部署必需

服务器可通过其访问的主机名列表，以逗号分隔—— 仅主机名，不含协议和端口：

I14Y_MCP_ALLOWED_HOSTS=i14y-mcp.up.railway.app,mcp.example.ch

此值会与传入的 Host 标头进行字面比较，因此 https://i14y-mcp.up.railway.app 或末尾带有 :443 都无法匹配，所有 请求都会失败并返回 HTTP 421 Invalid Host header。使用 TLS 时，浏览器 发送的是不带其他内容的主机名；非标准端口需要使用 SDK 唯一的通配符形式 host:*。无论哪种情况，环回地址都仍可访问，因此不会影响容器健康检查。

在非环回地址上绑定时，如果未设置此项，不会回退到安全的默认值。 服务器无法猜测访问它时使用的名称，而猜测的列表会拒绝所有真实请求，因此 服务器会完全关闭 Host 检查，并在日志中说明：

dns_rebinding_protection_off

railway.json

railway.json 固定了部署无法自行正确选择的唯一构建设置：

{ "build": { "builder": "DOCKERFILE", "dockerfilePath": "Dockerfile" } }

使用其他任何构建器时，Railway 都不会查看 Dockerfile。它会自行生成启动 命令，且 I14Y_MCP_TRANSPORT 不会在任何地方设置，于是 main() 会进入 stdio 分支——容器虽会运行，却不会开放端口，唯一的迹象就是健康检查失败。 如果该设置发生变化，tests/test_entrypoint.py 会失败。

此文件有意不包含以下两项：

• 不包含环境变量。 Railway 的架构在任何层级都没有对应的键，因此 I14Y_MCP_ALLOWED_HOSTS 和 I14Y_MCP_TRANSPORT 应设置在服务变量中。问题在于， 架构会验证 值，却会放过 自创的键：添加 "variables": { … } 块会通过 验证，编辑器也不会报错，但 Railway 会忽略它。测试会拒绝此类键。
• 不包含 healthcheckPath。 根据组装后的应用进行测试，没有任何路径会以 2xx 响应 GET 请求：/ 和 /health 返回 404，/mcp 在没有会话时返回 400， 在 Host 不匹配时返回 421。若将健康检查指向其中任何一个路径，部署都会被 标记为不健康并回滚。Dockerfile 中的 TCP 检查才是正确做法。如果服务器今后 增加了真正的健康检查路由，则可以设置此键——届时测试会要求该路径确实能响应。

CORS 会公开 Mcp-Session-Id 标头，以便浏览器 MCP 客户端保留会话。哪些浏览器 来源可以调用服务器，由 I14Y_MCP_CORS_ORIGINS 指定，该值是以逗号分隔的列表—— 未设置表示完全不允许浏览器客户端访问，这是默认行为。仍接受 *，并会记录 警告。无论如何，这都不会影响 stdio 和其他非浏览器客户端。

Docker

docker compose up --build      # Streamable HTTP on http://localhost:8000/mcp

该镜像采用强化的多阶段构建：以非 root 用户运行，不包含构建工具，也不需要 机密（API 未进行身份验证）。请参阅 Dockerfile 和 compose.yaml。

---

关联键

I14Y 是一个连接器层。两个标识符使其能够与产品组合中的其他部分进行组合：

键	字段	关联对象
瑞士 UID	Publisher.uid	register-mcp（Zefix）
端点 URL	DataServiceSummary.endpoint_urls	包装该 API 的任意产品组合服务

---

已知限制

于 2026-07-21 在线验证。

1. 搜索索引仅覆盖约一半的目录。 search_catalog 最多返回 1013 条记录；list_datasets 可返回约 2003 条。需要完整结果时，请使用 list_datasets。
2. 搜索仅返回数据集。 即使这些实体确实存在，按 types=["Concept"] 或 types=["DataService"] 筛选也不会返回任何结果。请改用 list_concepts 和 list_data_services。
3. 上游会忽略搜索分页。 始终返回完整结果集；本服务会将结果限制为 200 条，并设置 truncated: true。
4. 许可因分发项而异，而非因数据集而异。大多数分发项采用 «Opendata BY ASK»，要求注明出处，并限制商业用途。 重新使用前，请务必查看 licence 字段。
5. 有些元数据字段为空。 发布者可选择不填写频率、时间覆盖范围和分发格式，因此这些字段经常未设置。这是目录的数据质量特征，并非本服务的错误。
6. 并非每个带有端点的条目都有 URL。 对于仅标记为 «OpenAPI Spezifikation»、但没有 URI 的条目，本服务会将其显示为 (no URI) <label> 而非直接丢弃。

---

测试

PYTHONPATH=src pytest tests/ -m "not live"   # offline, used in CI
PYTHONPATH=src pytest tests/ -m "live"       # hits the real API
PYTHONPATH=src pytest tests/                 # everything
python -m ruff check src tests

在线测试并非摆设：探测报告中的第 4 个发现——关键词将其语言对象嵌套在 label 下——是在单元测试已全部通过后，由在线测试发现的。

---

贡献

有关基本规则（只读、单个出口主机、不包含机密）和本地开发循环，请参阅 CONTRIBUTING.md。维护者可参阅 PUBLISHING.md，了解 PyPI / MCP Registry 发布流程。

---

安全

有关安全状况以及如何报告漏洞，请参阅 SECURITY.md。

---

许可证

MIT 许可证——请参阅 LICENSE。目录数据仍受各发布者声明的条款约束。

---

作者

Hayal Oezkan · github.com/malkreide

---

致谢与相关项目

• 数据：I14Y Interoperability Platform，联邦统计局（BFS）
• 标准：eCH-0200 / DCAT-AP-CH
• 源发现灵感来自 rnckp/awesome-ogd-switzerland
• 作品集：swiss-public-data-mcp
• 协议：Model Context Protocol

许可证：MIT。目录数据仍受各发布者声明的条款约束。

---

MCP Registry

MCP Registry 使用的所有权标记，用于将此 PyPI 包关联到 GitHub 命名空间：

mcp-name: io.github.malkreide/i14y-mcp