switzerland-parliament-mcp-server

---

概览

瑞士联邦议会记录来自 Curia Vista 和 Amtliches Bulletin。查找议会事务、阅读原文及程序历史、跟进两院的辩论、查看国民院点名表决，并查询议员及其申报利益。使用公共 OData 服务，无需 API 密钥；可作为 STDIO 进程或本地 Streamable HTTP 服务运行。

结果注明来源为 Parlamentsdienste der Bundesversammlung, Bern，并附上来源 URL 和下载日期。这是非官方复刻。来源内容适用议会开放数据条件；底层作者权利仍然有效。

工具

工具	描述
chparl_search_business	按标题、提交人、类型、状态、提交届次、日期或委员会角色查找议案
chparl_get_business	读取议案元数据、原文、状态历史、法案、相关议案、委员会咨询或辩论主题
chparl_get_votes	查找 Nationalrat 点名表决、分页查看议员决定，或读取完整的表决及党团统计
chparl_search_transcripts	按议案、主题、发言者、届次、议院或日期查找辩论段落；获取原文
chparl_search_members	按姓名、议院、州、政党或党团查找现任或前任议会成员的任职记录
chparl_get_member	读取议会身份、议院任期、委员会成员资格或申报的利益
chparl_list_reference	查询标识符、覆盖范围、语言、代码、委员会和届次

功能参考

chparl_search_business _工具

• query 匹配一个标题子字符串；author 匹配已公布的提交人标签，而非所有联署人。可选的 typeId、statusId、sessionId、committeeId、submittedFrom 和 submittedTo 可进一步筛选；日期范围包含起止日期，届次指提交届次
• 按规范议案 ID 从新到旧排序，每页默认 20 条，最多 100 条。使用 nextCursor 和不变的筛选条件继续查询；不匹配的游标会返回 invalid_cursor
• 委员会搜索会检查角色候选项并返回不同议案，因此分页结果可能较少，且可能不包含 totalCount。不使用委员会筛选条件时，如果提供了原始筛选条件，totalCount 就是符合这些条件的议案数
• 将返回的 businessId 传递给 chparl_get_business、chparl_get_votes 或 chparl_search_transcripts

---

chparl_get_business _工具

• 接受规范的八位数 businessId 或精确的已公布短编号，例如 99.1234；有歧义的短编号会返回 ambiguous_business_number。overview（默认值）返回元数据和以 UTF-8 字节数表示的 availableTextFields
• section: "texts" 返回 textDocument.kind: "full" | "outline"。如果多个字段有内容导致完整结果达到 24,000 字节，自动披露会改为按字段大小列出概要；显式选择 textFields 或仅有一个字段有内容时，会返回完整内容，即使超过该阈值也一样
• 可选择 description、initialSituation、proceedings、draftText、submittedText、reasonText、documentationText、motionText、federalCouncilResponseText 或 federalCouncilProposalText。未公布的选项会显示在 unavailableTextFields 中；原始 HTML、空白字符和换行符保持不变
• status_history、bills、related_business、preconsultations 和 subjects 独立分页：每页默认 20 条，最多 100 条，并使用 nextOffset。分页仅适用于这些部分；textFields 仅适用于 texts
• 找不到议案时返回 found: false。关联法案是议会记录，并非已颁布的法律文本；可使用 subjects 缩小大型辩论的范围

---

chparl_get_votes _工具

• 从 mode: "votes" 和 businessId 开始获取唱名表决元数据，每页默认 10 条／最多 50 条。然后使用返回的 voteId，通过 mode: "members" 获取成员信息（每页默认 50 条／最多 100 条，可选 personNumber），或通过 mode: "groups" 获取完整结果（不分页）
• 成员唱名表决数据涵盖自 2003 年冬季会期起的 Nationalrat。此处没有 Ständerat 成员的表决决定；结果为空并不能证明没有发生表决
• members 返回 decisionCounts.scope: "page"；groups 会读取所有已发布的成员记录，然后返回 scope: "vote"、complete: true 和各组统计总数。成员数据不可用时，不会推断完整的零表决统计
• 统计所用的党派归属取自表决记录，而非当前成员身份。原始决定标签、未知代码和缺失的决定仍会显示；已记录的代码包括：1 赞成、2 反对、3 弃权、6 根据第 57 条第 4 款请假，以及 7 议长不投票
• 分页模式使用 nextOffset 继续；found: false 用于区分找不到议案或所选表决与子集合为空

---

chparl_search_transcripts _工具

• 公报数据覆盖自1999 年冬季会期起的两个议院。至少提供 businessId、subjectId、personNumber、sessionId、日期界限之一，或精确的 transcriptId；仅提供议院不足以进行搜索
• query 用于搜索原文中的一个子字符串，且还必须提供 sessionId，或闭合的 dateFrom／dateTo 日期范围（最多 31 个自然日，含首尾日期）
• 默认搜索结果仅返回元数据和 textSizeBytes，每页默认 20 条／最多 100 条。includeText: true 会返回完整段落，默认 3 条／最多 10 条。使用 nextOffset 和不变的筛选条件继续获取
• 精确的 transcriptId 默认返回全文，除它之外仅接受 language 和 includeText；显式设置 includeText: false 则返回元数据。文稿和主题 ID 保持为十进制字符串
• businessId 和 subjectId 不能同时使用。议案搜索会涵盖所有相关主题，最多 20 个；business_scope_too_broad 表示更大范围的辩论应先通过 chparl_get_business 的 subjects 部分查询，然后使用单个 subjectId
• metadataLanguage 不会翻译发言者的文本；缺少 languageOfText 时，该语言仍为未知。found 用于标识精确 ID 未命中的情况；scopeFound 用于区分找不到议案与议案存在但没有段落

---

chparl_search_members _工具

• query 用于匹配已发布的名字、姓氏或官方名称子字符串。membership 可设为 current（默认）、former 或 all；可选的 council、cantonId、partyId 和 groupId 可进一步缩小范围
• 结果是 MemberCouncil 归属记录，不会按人员去重。每页默认 20 条／最多 100 条，使用 nextOffset 继续获取
• 使用 personNumber 获取个人资料和成员决定筛选结果；它不一定等于 Person.ID。议院选择器接受 N／S，以及准确的德语、法语或意大利语议院名称

---

chparl_get_member _工具

• 必须提供 personNumber。overview（默认）会返回议会身份信息和所有基础 MemberCouncil 归属，不分页
• council_terms、committees 和 interests 分别分页，每页默认 20 条／最多 100 条，使用 nextOffset 继续获取；overview 不使用分页参数
• 委员会记录是已发布的成员资格，并非完整的历史委员会名册。缺少 paid 标记表示未知；利益记录为空并不能证明不存在利益冲突
• 找不到身份信息时会返回 found: false，并提供查询指引

---

chparl_list_reference _工具

• 主题：identifiers、coverage、languages、business_types、statuses、councils、cantons、parties、groups、committees 和 sessions。在其他工具中使用返回的 ID
• 默认每页 50 条／最多 100 条，通过 nextOffset 继续。只有 sessions 接受日期：dateFrom 限定会议开始日期，dateTo 限定会议结束日期，均包含边界日期
• statuses 是截至 2023 年 7 月 1 日生效的官方历史／当前词汇快照，并标明 era；未知的实时代码仍会显示。标识符、覆盖范围和语言的说明是静态的；其他词典均为实时数据

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none／jwt／oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志和可选的 OpenTelemetry 跟踪。

瑞士议会专属功能：

• 无需密钥，只读访问议案、程序关系、国民院唱名表决、辩论段落、议员及申报利益
• 提供 de（默认）、fr 和 it 元数据，不使用翻译回退。意大利语字段是否完整尚未确定；不提供英语和罗曼什语翻译
• 已发布的文本和 HTML 保持不变；随附的链接／图像引用索引保留原始属性，并在可用时提供可点击的绝对 HTTP(S) URL
• 每个完整工作流的时限为 45 秒；范围较窄的文本查询有助于应对上游搜索缓慢的问题

便于 Agent 使用的输出：

• content[] 和 structuredContent 均包含相同的记录、来源信息、筛选条件、通知和分页信息。多行文本和 HTML 会以 JSON 编码形式置于围栏文本块中，以便无损还原
• 集合会报告 returnedCount、分页时的 effectiveLimit、hasMore，以及可用时的续页信息；只有在已知时才会提供 totalCount。实时数据更新可能导致偏移分页发生变化
• 集合回复会围绕 24,000 字节的结果预算保留完整记录；为适应预算可缩短页长，但绝不会缩短返回字段。不可拆分且超出预算的记录会完整返回，并附带通知；文本选取、议员概览和团体总数也会保持完整
• 缺失值仍标记为未知；空结果会附带指引，达到速率限制时会返回 upstream_rate_limited 和重试指引

开始使用

自托管／本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "switzerland-parliament-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/switzerland-parliament-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "switzerland-parliament-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/switzerland-parliament-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "switzerland-parliament-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/switzerland-parliament-mcp-server:latest"]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户。

安装

1. 克隆代码仓库：

git clone https://github.com/cyanheads/switzerland-parliament-mcp-server.git

2. 进入目录：

cd switzerland-parliament-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# Optional: edit framework transport, auth, logging, or telemetry settings

配置

无需设置服务专用环境变量。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

常见框架覆盖项请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

项目结构

目录	用途
src/index.ts	createApp() 入口和服务设置；包含七个工具，没有资源或提示词。
src/mcp-server/tools	工具定义、共享的无损呈现和完整记录分页适配。
src/services/parliament	OData 客户端、工作流截止时间、领域架构和服务、来源溯证及参考快照。
tests/	单元测试和集成测试，与 src/ 结构对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。