sweden-parliament-mcp-server

---

概述

瑞典议会记录来自 Riksdagen Open Data。查找提案和委员会报告，追踪已公布的决议和主要投票，阅读演讲，查看议员任职情况，并检索整合后的 SFS 法规。可作为 stdio 进程或本地 Streamable HTTP 服务运行；无需 API 密钥。

来源：瑞典议会。本独立服务并非由 Sveriges riksdag 运营或认可。瑞典语标题、标签、决议和文本均保留来源原文；仅在来源提供英语标签时显示英文标签。

工具

工具	说明
riksdag_list_reference	浏览官方文件类型、委员会、政党、选区、会期，以及标识符和数据覆盖范围说明
riksdag_search_documents	按词语、类型、会期、委员会、政党或日期搜索议会文件和整合后的 SFS 法规
riksdag_get_document	查看发布元数据、决议、保留意见、活动、链接和分页文本
riksdag_search_speeches	按辩论标题、议员或政党查找某一会期内的演讲；通过 get 模式检索全文
riksdag_get_votes	查看报告决议及按政党汇总的主要投票数，或某位议员在某一会期的主要投票记录
riksdag_search_members	按姓名、政党、选区和来源服务分类查找登记条目
riksdag_get_member	查看精确的议员 IID 及其已公布的任职历史

功能参考

riksdag_list_reference _工具

• topic：document_types、committees、parties、constituencies、speech_types、sessions、identifiers 或 coverage
• 带日期的离线快照，包含瑞典语标签、可用的来源英文标签、来源链接和 referenceVerifiedAt；文件子类型与父代码保持分开，会期目录可能滞后于当前会期
• 使用 offset 分页；limit 默认为 20，最大为 100，并提供 totalCount 和完整的 nextCall 参数

---

riksdag_search_documents _工具

• 可选参数：query、documentType、session、committee、party、dateFrom 和 dateTo；日期格式为 YYYY-MM-DD，并接受代码或精确的参考标签
• 远程 page 从 1 开始；pageSize 默认为 10，最大为 50。返回每条已获取的记录，并保留来源排序；提供可用的 totalCount 和 nextCall
• 合并法规请使用 documentType: "sfs"；缓慢的全文搜索请使用 session 或 documentType 缩小范围

---

riksdag_get_document _工具

• 必填 documentId，取自搜索结果；也可使用明确无歧义的 SFS 标识符，例如 1974:152；找不到记录时返回 found: false
• 省略 sections 时，返回元数据、完整大纲和第一页文本；可选择 metadata、decisions、reservations、activities、properties、attachments、references、text 或 source_html
• 文本和 HTML 使用 Unicode 码点偏移量（textOffset / htmlOffset）；长度默认为 1,000，并遵循显式指定的 textLength / htmlLength 值。数组分区使用 sectionOffset / sectionLimit（默认为 20，最大值为 100）
• 使用 nextTextCall、nextHtmlCall 或各 sectionPages[].nextCall 获取后续内容，并保留 revision；记录变更时会返回 revision_changed。附件仅提供链接，不会下载文件
• SFS versionKind: "consolidated" 表示已发布的合并文本，其中可能包含未来生效的条款；它不是颁布时版本，也不是特定时间点的法律版本

---

riksdag_search_speeches _工具

• mode: "search"（默认值）要求提供 session；可选的 memberId、party 和 speechType: "all" | "speech" 可缩小选择范围，其中 speech 会排除答复
• headingContains 会匹配标题和副标题中的所有词元，不区分大小写和变音符号；不会搜索演讲正文
• 使用本地 offset 分页；limit 默认为 5，最大为 20。textCount 默认为 1，最大为 5；设为 0 时仅返回元数据
• mode: "get" 要求提供从搜索结果中复制的检索用 speechId，而不是 sourceSpeechId。get 模式不接受搜索筛选条件。textOffset 和可选的 textLength 用于读取已发布的完整正文，并通过 nextTextCall 获取后续内容；默认文本页为 1,000 个码点
• textState 的值为 included、not_requested、unavailable 或 failed；暂时性内容加载失败会附带恢复详情。在搜索或文本续传时保留 revision

---

riksdag_get_votes _工具

• 必填 mode 和 session；mode: "report" 接受 report（议案编号或 session:designation）或报告的 documentId；mode: "member" 要求提供 memberId，并允许提供 party
• report 模式返回权威决议和完整的党派分组。选择一个 point，或使用 pointOffset / pointLimit（默认为 5，最大值为 10）；member 模式使用 offset / limit（默认为 20，最大值为 500）
• 仅包含已发布的主表决，不包含每一轮投票。rollCallState 的值为 available、acclamation、not_published 或 unknown；只有存在明确的决议证据时才能判定为鼓掌通过，不能仅凭投票记录为空来判定
• 缺失的汇总计数仍视为未知；来源中额外的投票标签会保留在 otherVotes 中。使用 nextCall 获取剩余的完整议题或议员记录，并保留 revision

riksdag_search_members _工具

• 可选参数 nameContains 会忽略大小写和变音符号，匹配所有词元；party 和 constituency 接受代码或完全匹配的参考标签
• sitting: "all" | "serving" | "not_serving" 默认值为 all；此参数筛选源数据中的任职分类，并非已验证的在会或当选成员身份。结果可能包含历史条目和部长；分类未知的条目仍会包含在 all 中
• 使用本地 offset 分页；limit 默认值为 20，且上限为 100。返回 candidateCount、筛选后的精确 totalCount、revision 和 nextCall
• memberId 中的前导零必须保留。部分欧洲议会条目没有 IID，会返回 detailAvailable: false；其 sourceRecordId 是不同的标识符，不能用于 riksdag_get_member

---

riksdag_get_member _工具

• 必须提供从搜索结果中获得的数字字符串 memberId，包括前导零；找不到条目时会返回 found: false 并提供指引
• 按来源顺序提供已发布的登记册元数据和任职信息；assignmentOffset / assignmentLimit 默认值分别为 0 / 20，实际应用的上限为 100
• assignmentTotal、nextCall 和 revision 支持完整遍历。任职日期保留来源精度，不能据此确定历史在会状态；不包含联系方式和照片

功能

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

Riksdag 专属功能：

• 无需密钥即可访问官方文件、演讲、投票和成员端点，以及带日期的官方参考表
• 文件文本支持规范 Markdown 或 SFS 源文本，并可单独选择原始 HTML
• 共享上游并发控制、限制公共响应缓存，并为排队、重试和文本填充共用一个 55 秒的时限
• 历史覆盖范围因记录类型而异；演讲和投票数据始于 1993/94 年，较早的投票数据存在缺失

面向 Agent 的输出：

• 在 content[] 和 structuredContent 中提供来源归属、检索时间、实际筛选条件和来源警告
• 为行、章节和文本提供完整的续传调用，并在本地续传时检查版本；变化中的远程文件搜索并非冻结快照
• 明确表示未找到、文本不可用、数量未知和来源任职分类；候选项数量达到上限时会报错 candidate_limit_reached，而不会返回不完整的遍历结果

开始使用

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

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

或使用 npx（无需 Bun）：

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

或使用 Docker：

{
  "mcpServers": {
    "sweden-parliament-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/sweden-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+）。
• Riksdagen Open Data 无需 API 密钥或账户。

安装

1. 克隆代码库：

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

2. 进入目录：

cd sweden-parliament-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env for optional transport, authentication, or logging overrides

配置

变量	描述	默认值
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	注册七个工具、初始化服务，并选择无状态 HTTP 会话。
src/mcp-server/tools/definitions	七个只读工具定义；没有资源或提示词。
src/services/riksdag	Riksdagen 端点解析、参考表、传输、缓存、文本转换和续传。
tests/	单元测试和集成测试，结构与 src/ 对应。

完整文件树请参阅 docs/tree.md。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

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

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。