Swiss Grounding

Swiss Grounding MCP

关于瑞士的问题，答案附有来源。

一个 MCP 服务，让 AI 助手基于瑞士联邦、州和市镇的官方信息作答，
支持德语、法语、意大利语、罗曼什语和英语，并在每个回答中注明相关主管机构。

立即体验

扫码即可在手机上打开

运行于苏黎世的 Google Cloud Run（europe-west6），由 main 部署。 公开且只读：无需注册，无需 API 密钥。 线上服务： swiss-grounding-mcp-542630986415.europe-west6.run.app MCP 端点（Streamable HTTP）： https://swiss-grounding-mcp-542630986415.europe-west6.run.app/mcp 运行状况： /health

只需一行即可将其添加到助手中，例如 Claude Code（其他客户端）：

claude mcp add --transport http swiss https://swiss-grounding-mcp-542630986415.europe-west6.run.app/mcp

空闲时会缩至零，因此暂停后收到的第一个请求会启动一个实例（约需 2 秒；混合搜索约 10 秒后启动，此期间会提供关键词搜索答案）。服务按客户端限流，拒绝浏览器来源，并且每 6 小时检查一次。托管实例运行的是本仓库中的代码，该代码也可在本地运行。

工作原理

向通用助手询问瑞士相关问题，它可能会回答错误州份的信息、过时网页上的信息，或邻国的信息。Swiss Grounding MCP 为它提供主管机构自己的数据：

1. 一次工具调用。 助手选择 13 个只读工具之一。地点名称可以使用人们惯用的写法： Genf, Ginevra, Genève、Schuls → Scuol、8003、Bahnhofstrasse 1, Zürich。
2. 正确的主管机构。 答案来自负责的层级（联邦机构、州或市镇），通过包含 10,630 个官方页面的预建索引（关键词 + 多语言语义搜索）、实时联邦 API 和市镇开放数据获取。
3. 礼貌且可靠。 默认遵守 robots.txt 和使用条款，控制请求频率并缓存数据；如果数据源不可用，则提供注明日期的副本，或指出该数据源。
4. 一条带引用的答案。 每个工具都返回相同的约定，其中包含原文摘录和五种状态之一，告知助手应如何处理：

覆盖范围

声明的范围：服务会回答什么问题、涉及哪个区域、依据哪个权威来源。助手也可以使用 swiss_coverage 工具读取此信息。

未涵盖的内容和已知限制

• 瑞士以外的任何内容，例如康斯坦茨的德国 Rundfunkbeitrag：服务端会说明这一点。
• GR、BL 和 SH 州会屏蔽自动化客户端，或不向其提供文本，因此这些州的州级页面未纳入索引（ch.ch 和联邦页面仍可用；read_official_page 会如实报告屏蔽情况）。VS（7 个页面）、TI（45 个）和 TG（52 个）仅部分纳入索引。
• 市政网站页面已为上述九座城市建立索引（每座 120–250 个页面；洛桑 66 个，图恩 32 个）。苏黎世仅有少数页面，贝林佐纳和弗里堡尚无页面（下次刷新时会抓取弗里堡自己的域名 ville-fribourg.ch）。对于其他市镇，服务端会返回官方网站，并可实时读取指定页面。
• 垃圾回收日历仅在市镇发布开放数据时提供；其他情况下，服务端会说明这一点并链接到市镇网站。节假日、保费和地点信息涵盖所有市镇。
• 州法律文本、个人税务计算和天气预报不在提供范围内。
• 学校假期数据来自汇总官方列表的 OpenHolidays。如果索引中有主管机构自己的日历（例如 ge.ch、bern.ch 和 Scuol 学校），则会优先引用该页面，并同时列出 EDK 列表和市镇网站链接。如果某个州发布了多种学校类型的假期安排，则会标注学校类型（伯尔尼州：德语区和法语区学校）。
• 抵达后在洛桑登记的相关信息较为薄弱：该市居民办公室的页面未纳入索引。
• **跨语言问题：**如果提问所用语言与地点页面的语言不同，系统会先返回语言提示，而不是页面；助手必须重新搜索。在此类问题的端到端测试中（用法语询问伯尔尼），Sonnet 遵循提示并根据伯尔尼页面作答；Haiku 在 4 次测试中有 1 次这样做。
• 默认情况下，搜索基于关键词。启用可选的 semantic 扩展后，搜索会采用混合模式，也能找到措辞不同或使用其他语言编写的页面，但仍会漏掉一些页面（测量结果）；嵌入模型不支持罗曼什语。

结果

**使用和不使用此服务端的对比。**将同样的 28 个问题（已发布的 5 个示例、我们自拟的 12 个问题，以及组织方提供的 11 个练习案例）以三种仅工具不同的方式提交给使用 Sonnet 的 Claude Code：

使用此服务端时，回答所需的调用次数和时间也只有网页搜索的一半（每个问题 1.2 次对 2.4 次调用，14 秒对 28 秒）。网页搜索通常能找到正确数值，但也会混入比价网站、新闻和旅游页面，并对官方数据进行取整；不使用任何工具时，模型大多会拒绝回答，或依据过时知识作答。

**不同评测设置的结果：**2 个 MCP 客户端 × 2 个大模型，测试 5 个已发布的示例问题和我们自拟的 11 个问题（德语／法语／意大利语／罗曼什语／英语，包括追问、超出范围和未涵盖的案例），测试日期为 2026-09-25：

在组织方的练习题集中：Sonnet 为 11/11，Haiku 为 10/11。对于 38 个带标签的问题，混合搜索有 25 个能找到相关官方页面（仅关键词搜索时为 19 个）；对于没有相关页面的 5 个问题，则不会误报其他页面。所有未命中案例均列于 docs/evaluation.md。

自行运行

需要 uv（它会安装 Python 3.13）。任何数据源都不需要 API 密钥或凭据。

git clone https://github.com/Gastaan/swiss-grounding-mcp && cd swiss-grounding-mcp
uv sync --extra semantic                                                  # dependencies, with hybrid search
uv run --extra semantic swiss-grounding-mcp                               # stdio (for local MCP clients)
uv run --extra semantic swiss-grounding-mcp --transport http --port 8000  # HTTP: http://localhost:8000/mcp
curl localhost:8000/health                                                # "search": "hybrid (…)"

预构建的数据（市镇名录、医疗保险费、搜索索引、段落向量）已包含在仓库中，由 scripts/ 中的脚本构建并每周更新（了解详情）。首次启动时会解压索引（约 1 秒），并在后台下载小型嵌入模型（约 240 MB，一次性下载；模型就绪前，搜索会使用关键词）。如需更轻量的安装且不使用混合搜索，可从命令和客户端配置中移除 --extra semantic（了解变更内容）。

**Docker：**已发布的镜像（约 1.4 GB，包含混合搜索及其模型）以非特权用户身份运行，且运行时不会下载任何内容。

docker run -p 8000:8000 ghcr.io/gastaan/swiss-grounding-mcp                # HTTP: http://localhost:8000/mcp
docker run -i --rm ghcr.io/gastaan/swiss-grounding-mcp --transport stdio   # for a client that starts the server

或者，使用 docker build -t swiss-grounding-mcp . 构建。如果端口可从受信任网络之外访问，请添加 -e SGM_AUTH_TOKEN=<secret>（HTTP 安全性）。无需克隆（关键词搜索）：uvx --from git+https://github.com/Gastaan/swiss-grounding-mcp swiss-grounding-mcp。

连接 MCP 客户端

任何支持通过 stdio 或 Streamable HTTP 使用 MCP 的客户端都可以使用。已使用 Claude Code、OpenCode、MCP Inspector CLI 和 FastMCP 客户端进行测试，包括旧版 initialize 握手（协议 2025-06-18）和无状态的 2026-07-28 协议。对于托管服务，请将其 /mcp URL 添加为远程（HTTP）服务。对于克隆的仓库，请使用绝对路径，并替换 /path/to/swiss-grounding-mcp。服务会向客户端发送用法 instructions。

claude mcp add swiss -- uv run --extra semantic --directory /path/to/swiss-grounding-mcp swiss-grounding-mcp
claude mcp add --transport http swiss-http http://localhost:8000/mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "swiss": {"type": "local", "command": ["uv", "run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"], "enabled": true, "timeout": 30000},
    "swiss-http": {"type": "remote", "url": "http://localhost:8000/mcp", "enabled": false, "timeout": 30000}
  }
}

{"mcpServers": {"swiss": {"command": "/full/path/to/uv", "args": ["run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"]}}}

{"servers": {"swiss": {"type": "stdio", "command": "uv", "args": ["run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"]}}}

{"mcpServers": {"swiss": {"command": "uv", "args": ["run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"]}}}

提示

将客户端的请求超时设为 30 秒或更长。OpenCode 默认只等待 5 秒，而官方数据源响应较慢时可能需要更久；服务会在 SGM_TOOL_TIMEOUT（30 秒）内结束每次工具调用，并返回清晰的 source_error，因此将客户端超时设为 30 秒即可收到该响应。

配置

无需配置。默认启用对 robots.txt 和使用条款的遵守，也可以将其关闭：

缓存、超时、离线模式、Bearer 令牌、速率限制、允许的来源和日志记录请参阅 docs/configuration.md。

文档

• 响应约定与工具：每个工具返回的 JSON、五种状态、地点处理方式以及全部 13 个工具
• 配置与运维：所有设置、HTTP 安全性、缓存与数据源使用规范、监控以及托管实例
• 搜索：关键词和语义排序及其测得的质量
• 评估：挑战自检、端到端运行以及所有已知的遗漏
• 开发：架构、数据及其每周更新、添加数据源和测试

_{为 Swiss AI Weeks 2026 苏黎世举办的 Swisscom myAI 挑战赛 Swiss Grounding MCP 打造。}