swiss-cultural-heritage-mcp

🇨🇭 属于 Swiss Public Data MCP Portfolio 的一部分

🏛️ swiss-cultural-heritage-mcp

瑞士文化遗产 MCP 服务——SIK-ISEA 艺术家、Nationalmuseum 馆藏和 Nationalbibliothek 书目

🇩🇪 德语版

---

概览

swiss-cultural-heritage-mcp 无需身份验证，即可通过 AI 原生方式访问瑞士文化遗产数据源：

来源	数据	API
SIK-ISEA (SIKART)	约 17,000 位瑞士艺术家——SIKART 传记数据	opendata.swiss CKAN
Nationalmuseum (SNM)	博物馆馆藏（钱币学、印章、特别馆藏）	opendata.swiss CKAN
Nationalbibliothek (NB)	瑞士国家书目（Helveticat）	SRU（搜索）+ OAI-PMH（馆藏）
Memoriav / Memobase	视听遗产（照片、音频、视频）	关联开放数据（JSON-LD / Hydra）
Dodis	瑞士外交文献（文件、人物、组织）	JSON-REST（Solr）+ 永久链接

该服务补足了瑞士公共数据组合中的人文维度——历史、文学与艺术，与现有法律 (fedlex-mcp)、交通、统计等服务相辅相成。

记忆机构门面（Memobase + Dodis）通过三个联合检索工具提供——search_heritage、get_heritage_item、list_heritage_collections——而非为每个来源分别设置一组工具。每项结果都包含来源、永久链接和许可信息，并且分别报告元数据和数字化对象的许可信息（两者可能不同：元数据是开放关联开放数据，但数字化对象可能受版权保护）。返回的只有元数据和链接——不会复现受版权保护的全文（例如 Dodis 的转录文本）。

示例查询（艺术）： “查找 Nationalmuseum 中 19 世纪在苏黎世工作的画家的作品，并与 SIK-ISEA 艺术家数据库中的传记交叉参照。”

示例查询（记忆机构）： “瑞士记忆机构中有哪些关于 19 世纪苏黎世 Volksschule 发展的资料？” → search_heritage(query="Volksschule Zürich", collection="all", date_from="1800", date_to="1899")。

演示

---

功能

• 🏛️ 11 个工具、2 个资源、2 个提示词，涵盖五个数据源
• 🔍 heritage_cross_search——在一次调用中并行搜索 SIK-ISEA、SNM 和 NB
• 🏛️ search_heritage——在 Memobase 和 Dodis 上提供联合检索门面，每项结果均包含来源、永久链接，以及分别列出的元数据和数字化对象许可信息
• 🌐 双语输出（Markdown / JSON）
• 🔓 无需 API 密钥——所有数据均采用开放许可
• ☁️ 双传输方式——stdio（Claude Desktop）+ Streamable HTTP（云端）
• 📚 艺术研究和教育材料查找提示词模板

项目阶段： 阶段 1——只读。 每个工具都标注为 readOnlyHint: true；没有写入或破坏性操作。进入阶段 2（支持写入）需满足 docs/roadmap.md 中列出的先决条件。

---

先决条件

• Python 3.11+
• uv（推荐）或 pip

---

安装

# Clone the repository
git clone https://github.com/malkreide/swiss-cultural-heritage-mcp.git
cd swiss-cultural-heritage-mcp

# Install
pip install -e .
# or with uv:
uv pip install -e .

或者使用 uvx（无需永久安装）：

uvx swiss-cultural-heritage-mcp

---

快速入门

# stdio (for Claude Desktop)
python -m swiss_cultural_heritage_mcp.server

# Streamable HTTP (port 8000)
python -m swiss_cultural_heritage_mcp.server --http --port 8000

立即在 Claude Desktop 中试用：

“费迪南德·霍德勒是谁？” “瑞士国家博物馆有哪些来自苏黎世的硬币？” “在瑞士国家书目中查找有关 Volksschule 的出版物”

→ 按受众分类的更多用例 →

---

配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "swiss-cultural-heritage": {
      "command": "python",
      "args": ["-m", "swiss_cultural_heritage_mcp.server"]
    }
  }
}

或者使用 uvx：

{
  "mcpServers": {
    "swiss-cultural-heritage": {
      "command": "uvx",
      "args": ["swiss-cultural-heritage-mcp"]
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

云端部署（用于浏览器访问的 SSE）

通过浏览器中的 claude.ai 使用（例如，在没有本地软件的受管工作站上）：

Render.com（推荐）：

1. 将仓库推送到 GitHub，或在 GitHub 上复刻该仓库
2. 在 render.com 上：新建 Web 服务 → 连接 GitHub 仓库
3. 选择区域 Frankfurt（欧盟）——根据 revDSG / EDÖB 的规定，这是瑞士公共部门使用的必要条件。参见 docs/data-residency.md。
4. 设置启动命令：python -m swiss_cultural_heritage_mcp.server --http --port 8000
5. 在 claude.ai 的“设置”→“MCP 服务”中添加：https://your-app.onrender.com/sse

💡 “开发者笔记本电脑使用 stdio，浏览器使用 SSE。”

对于容器部署（Docker / Kubernetes / Cloud Run）：仓库提供了经过加固的 Dockerfile（非 root UID 10001）。关于推荐的 SecurityContext，请参见 docs/security.md；关于出口策略，请参见 docs/network-egress.md。该服务默认以单实例运行；水平扩展前，请参见 docs/scaling.md 了解会话亲和性的前提条件。

---

可用工具

SIK-ISEA（瑞士艺术研究）

工具	描述
heritage_search_artists	按姓名或地点搜索约 17,000 位瑞士艺术家（SIKART）
heritage_get_artist	根据 SIKART ID（HAUPTNR）获取完整艺术家档案

Nationalmuseum（SNM）

工具	描述
heritage_search_museum_datasets	搜索 opendata.swiss 上的 SNM 数据集
heritage_browse_collection	通过 CKAN DataStore 浏览某个馆藏中的藏品

Nationalbibliothek（NB）

工具	描述
heritage_search_helveticat	对全部馆藏进行全文搜索（SRU），或浏览单个馆藏（OAI-PMH）
heritage_list_nb_collections	列出 68 个可用的 OAI-PMH 集合
heritage_get_publication	获取一条出版物记录中经筛选的 MARC21 字段，并规范化为 Dublin Core 风格的键（OAI-PMH GetRecord）——不包含完整的目录记录

跨来源

工具	描述
heritage_cross_search	并行搜索 SIK-ISEA、SNM 和 NB

记忆机构（Memobase + Dodis）——联合门面

工具	描述
search_heritage	联合搜索 Memobase + Dodis（collection = memobase | dodis | all），支持 date_from / date_to / media_type 筛选条件。每条结果均包含来源、永久链接，以及分别标注的元数据和数字化对象许可证
get_heritage_item	获取单个对象的完整元数据（collection、item_id）。仅提供元数据和链接——绝不复现受保护的全文
list_heritage_collections	发现可用馆藏及其协议、身份验证方式和许可证——也包括已探测但未连接的来源（Bundesarchiv、Landesmuseum）及其原因

示例用例

查询	工具
“Ferdinand Hodler 是谁？”	heritage_get_artist
“查找出生于 Basel 的瑞士艺术家”	heritage_search_artists
“Nationalmuseum 收藏了哪些来自 Zurich 的钱币？”	heritage_browse_collection
“查找有关 Volksschule 的出版物”	heritage_search_helveticat
“搜索所有与 Sophie Taeuber-Arp 有关的内容”	heritage_cross_search
“瑞士记忆机构中有关 19 世纪 Zurich Volksschule 的资料”	search_heritage

---

架构

┌─────────────────┐     ┌──────────────────────────────┐     ┌──────────────────────────┐
│   Claude / AI   │────▶│  Swiss Cultural Heritage MCP  │────▶│  SIK-ISEA                │
│   (MCP Host)    │◀────│  (MCP Server)                │◀────│  opendata.swiss / CKAN   │
└─────────────────┘     │                              │     ├──────────────────────────┤
                        │  11 Tools · 2 Resources      │────▶│  Nationalmuseum (SNM)    │
                        │  2 Prompts                   │◀────│  opendata.swiss / CKAN   │
                        │  Stdio | SSE                 │     ├──────────────────────────┤
                        │                              │────▶│  Nationalbibliothek (NB) │
                        │  No authentication required  │◀────│  Helveticat: SRU, OAI-PMH│
                        │                              │     ├──────────────────────────┤
                        │  search_heritage facade      │────▶│  Memobase (JSON-LD/Hydra)│
                        │                              │◀────│  Dodis (JSON-REST/Solr)  │
                        └──────────────────────────────┘     └──────────────────────────┘

数据源特征

数据源	协议	覆盖范围	身份验证
SIK-ISEA (SIKART)	CKAN DataStore	约 17,000 位瑞士艺术家	无
Nationalmuseum	CKAN DataStore	博物馆藏品	无
Nationalbibliothek	SRU 1.2 (CQL) + OAI-PMH 2.0	瑞士国家书目	无
Memoriav / Memobase	关联开放数据 (JSON-LD / Hydra, RiC-O)	视听遗产（约 46 万条记录）	无
Dodis	JSON-REST (Solr) + 稳定永久链接	外交文件、人物、组织	无

架构决策 — 记忆机构门面

经 2026-07-19 的实时探测验证（方法：mcp-data-source-probe）。 我们评估了四家记忆机构；其中只有两家提供干净、无需身份验证的标准化接口，并已接入：

数据源	结果	原因
Memobase	✅ 已接入	关联开放数据 API（api.memobase.ch，JSON-LD/Hydra）；通过 ?q= 进行全文搜索，通过 /record/<id> 获取单条记录；通过 offset/size 分页。元数据开放；数字化对象带有对象级 rightsstatements.org 权利声明（“版权保护中”，访问方式为“现场”）。
Dodis	✅ 已接入	JSON-REST/Solr（beta.dodis.ch/api）：通过 POST /api/solr/query 搜索，通过 GET /api/solr/full/<id> 获取条目；稳定永久链接为 dodis.ch/<id>。元数据开放（需注明出处）；文件带有文档级权利声明（TEI/PDF 位于永久链接后）。
Bundesarchiv	⛔ 未接入	recherche.bar.admin.ch 后端（CMI AIS）需要通过 eIAM 登录和 Google reCAPTCHA 验证——若不模拟会话则无法通过机器访问，而模拟会话既脆弱，也违背运营方的意图。
Landesmuseum	⛔ 未接入	sammlung.nationalmuseum.ch 没有公共 API（只有内部且未公开文档的 Ajax/HTML 接口）——接入它需要进行网页抓取，这违反了韧性保障要求。

因此：提供三个联邦查询工具，而非四个工具类别；每条结果都包含来源 + 永久链接 + 分拆的元数据/数字化对象许可；不复现受版权保护的全文（仅提供元数据 + 链接）；bar 和 landesmuseum 在 list_heritage_collections 中注明为受限来源，不进行抓取。

---

项目结构

swiss-cultural-heritage-mcp/
├── src/swiss_cultural_heritage_mcp/
│   ├── __init__.py              # Package
│   └── server.py                # 11 tools, 2 resources, 2 prompts
├── tests/
│   └── test_server.py           # Unit + integration tests (mocked HTTP)
├── .github/workflows/ci.yml     # GitHub Actions (Python 3.11/3.12/3.13)
├── .github/dependabot.yml       # Monthly dependency + SDK update PRs
├── Dockerfile                   # Multi-stage, non-root, HEALTHCHECK
├── docs/                        # security, network-egress, scaling, data-residency, roadmap
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md                    # This file (English)
└── README.de.md                 # German version

**单文件服务：**11 个工具位于一个 server.py 文件中，而不是 tools/ 包。在目前的规模下，单个线性模块比拆分后的结构更易于阅读和审查；如果工具数量显著增加，SIK-ISEA / SNM / NB / 跨源搜索模块是最适合拆分的部分。

---

安全性与限制

• **只读：**所有工具仅执行 HTTP GET 请求，不会写入、修改或删除任何数据。
• **不处理个人数据：**这些 API 返回的是机构记录（艺术品、出版物、艺术家）。此服务不会处理或存储任何个人身份信息（PII）。
• **速率限制：**在 2026-09-20 进行的约 380 次探测请求中，未观察到限流。这并不代表已了解公开条款：本项目尚未核查国家图书馆的 SRU 和 OAI-PMH 使用条款（参见 PROBE_REPORT_helveticat.md）。请谨慎使用 limit 参数。此服务对每个请求设有 30s 超时。
• **数据时效性：**记录反映查询时上游来源的数据。此服务不会缓存数据。
• **服务条款：**数据受各来源的服务条款约束：SIK-ISEA、opendata.swiss、Nationalbibliothek。opendata.swiss 数据集采用开放许可（CC0 / CC BY）。对于国家图书馆，本项目尚未核实任一端点的条款。记录自带权利声明时，会以 rights（MARC 506/540）的形式提供；许多记录不带权利声明。署名页脚中的许可行是来源的通用声明，并非针对单条记录；JSON 响应则完全没有页脚。重新分发前，请向来源方核实。
• **不作保证：**此服务是社区项目，与 SIK-ISEA、SNM 或 NB 均无关联。可用性取决于上游 API。

---

已知限制

• **SIK-ISEA：**艺术家数据会定期更新；最新收录的藏品可能尚未反映在数据中
• **Nationalmuseum：**只能访问发布在 opendata.swiss 上的数据集；SNM 并非所有馆藏都可用
• Nationalbibliothek：maximumRecords 在服务端静默封顶为 50——请求更多记录时只会返回 50 条，不会发出警告。SRU 无法按 OAI 集合进行筛选，因此 query 和 set_spec 使用不同端点，无法合并为一次服务端搜索。from_date/until_date 指目录记录的修改日期，而非出版年份。测量日期为 2026-09-20；参见 PROBE_REPORT_helveticat.md。
• **跨来源搜索：**响应时间取决于三个来源中最慢的一个

---

测试

# Unit tests (no API key required)
PYTHONPATH=src pytest tests/ -m "not live"

# Integration tests (live API calls)
pytest tests/ -m "live"

# Lint and format, as CI runs them
ruff check src/ tests/ scripts/
ruff format --check src/ tests/ scripts/

Ruff 在 pyproject.toml 的 [project.optional-dependencies] dev 中固定为精确版本，因此执行 pip install -e ".[dev]" 会安装 CI 使用的版本，并使 lint 检查门槛保持一致。在此基础上安装较新版本的 ruff 会改变规则集和格式化程序，并报告无人改动的代码存在差异。参见 CONTRIBUTING.md。

---

MCP 协议版本

项目	值
SDK	mcp[cli]>=2.0.0,<3（固定在 pyproject.toml 中）
通过 initialize 握手提供	2024-11-05 … 2025-11-25 — 握手上限
通过逐请求信封提供	2026-07-28
由谁选择	客户端在每个连接的首次请求中选择：携带 2026-07-28 _meta 信封的请求会建立现代连接，其他请求则会建立握手连接。之后若声称属于另一时代，则会被拒绝。
更新策略	SDK 固定版本是协议版本的唯一依据。Dependabot 每月创建 mcp 更新 PR；协议版本升级会在此处审核，并记录在 CHANGELOG.md 中。

此服务不会覆盖协商结果——由官方 mcp SDK 决定，并且两个时代都可通过任一传输方式（stdio 和 HTTP 均可）访问。要控制使用哪些协议版本，请固定 SDK，而不是手动编写版本字符串。上面的数字来自固定版本 SDK 自己的注册表（mcp_types.version：HANDSHAKE_PROTOCOL_VERSIONS、MODERN_PROTOCOL_VERSIONS）——如果固定版本已变更，请从注册表中读取，而不要依赖此表。

这两个修订版本都在 tests/test_protocol_version.py 中固定，并与已安装的 SDK 进行断言验证——其中包括握手上限，该上限通过已组装的 ASGI 栈上的实时 initialize 测得。现在，Dependabot 对 mcp 的升级不会再悄然改变这两个数字，导致此表过时。

服务身份

字段	值	来源
name	swiss-cultural-heritage-mcp	__dist__ — PyPI 名称，也见于 server.json
title	Schweizer Kulturerbe	server.SERVER_TITLE
version	已发布的软件包版本	通过 importlib.metadata 从 pyproject.toml 获取
description	PyPI 上的一句话简介	pyproject.toml → [project].description
websiteUrl	项目主页	pyproject.toml → [project.urls].Homepage
instructions	此服务的用途	server.INSTRUCTIONS

标识符使用连字符，与仓库、PyPI 软件包和控制台脚本一致。Python 模块使用下划线——上文的 python -m swiss_cultural_heritage_mcp.server 并非不一致，而是 Python 允许的软件包名称的唯一写法。

2026-07-28 时代没有握手。SDK 不会在每个连接中发送一次 serverInfo，而是将身份信息写入每个响应的 _meta 中；server/discover 除了功能之外，恰好还携带一个字段： instructions。

SDK 本身不会提供这些信息——Server.server_info 明确说明：“未指定版本的服务会报告一个空的 version；SDK 不会用自身的版本替代。”截至 2026 年 9 月 18 日，此服务此前并未提供其中任何信息，每次调用都报告 "version": ""。现在，这一点已通过 tests/test_server_identity.py 进行测量，涵盖两个时代并通过真实 HTTP 请求验证：设置了构造函数参数，并不代表该字段已出现在传输内容中。

版本、描述和 URL 均为派生值，而非手动编写。已发布路径中的字面值会成为 pyproject.toml 之外的第二个事实来源——这正是 scripts/check_version_sync.py 禁止版本号出现的偏差。

---

更新日志

请参阅 CHANGELOG.md

---

贡献

请参阅 CONTRIBUTING.md

---

安全

请参阅 SECURITY.md（Deutsch），了解安全状况以及如何报告漏洞。

---

许可证

MIT 许可证 — 请参阅 LICENSE

---

作者

Hayal Oezkan · malkreide

---

致谢与相关项目

• SIK-ISEA： www.sik-isea.ch — 瑞士艺术研究所
• Nationalmuseum： www.nationalmuseum.ch / opendata.swiss
• Nationalbibliothek： www.nb.admin.ch — 瑞士国家图书馆
• 协议： Model Context Protocol — Anthropic / Linux Foundation
• 相关项目： eth-library-mcp — ETH 图书馆：覆盖整个瑞士图书馆（ETH = 科学，NB = 人文）
• 相关项目： fedlex-mcp — 文化遗产法与主要立法
• 相关项目： zurich-opendata-mcp — 空间历史数据：博物馆藏品与苏黎世地理数据
• 项目集： Swiss Public Data MCP Portfolio

安装

通过 uv 的 uvx 运行，无需克隆或手动安装。添加到 MCP 客户端配置中（Claude Desktop、Cursor 和 Windsurf 使用 mcpServers；VS Code 在 .vscode/mcp.json 中使用顶层 servers 键）：

{
  "mcpServers": {
    "swiss-cultural-heritage-mcp": {
      "command": "uvx",
      "args": [
        "swiss-cultural-heritage-mcp"
      ]
    }
  }
}