canada-parliament-mcp-server

---

概览

加拿大联邦议会记录来自 LEGISinfo、House of Commons 和 OpenParliament。跟进众议院和参议院法案的各个阶段，查找现任和前任议员，查看记录在案的众议院表决，并阅读已编入索引的众议院《议事录》演讲。公共来源无需 API 密钥。

工具

工具	说明
canparl_search_bills	按标题、编号、议院、类型、状态或已编入索引的提案议员搜索某一会期的官方法案
canparl_get_bill	查看官方法案档案：提案人和标题、阶段、宣读里程碑、表决、出版物、立法摘要、备注、网页参考资料及已颁布法规的引文
canparl_search_members	搜索众议院现任议员名册或 OpenParliament 的历史姓名索引
canparl_get_member	查看议员简介、注明日期的任职记录、提案法案和近期投票
canparl_search_votes	按法案、结果、文件类型、日期或主题搜索记录在案的众议院表决
canparl_get_vote	查看表决的官方票数、党派统计和个人记录投票
canparl_search_speeches	按发言人、辩论或提及的法案、日期和逐字英文文本查找已编入索引的众议院演讲
canparl_list_reference	查看实际会期覆盖范围和各来源特有的筛选词汇

功能参考

canparl_search_bills _工具

• titleContains、billCode、originatingChamber、billType、status 和 sponsor 组合使用 AND；limit 为 1–100（默认为 25；值最高为 10,000 时会截断为 100，并显示提示），支持通过 offset 分页
• 返回双语标题、状态、最新重要阶段和御准日期，并提供精确的筛选后 total 和 pagination.nextOffset
• 完整法案行会在达到 24,000 字节响应预算前停止；使用相同筛选条件跟进 pagination.nextOffset。若单行过大，则会完整返回并显示提示
• sponsor 接受 OpenParliament slug、/politicians/ 路径或个人资料 URL（来自 canparl_get_member 的 member.slug，或 includeFormer 搜索结果中的 slug），也接受现任 MP 的 personId。仅由数字组成且等于现任 personId 的值，或其 /politicians/<digits>/ 路径或 URL，会通过与 canparl_get_member 相同的已验证交叉映射进行解析；appliedFilters.sponsorName 会标明所使用的个人资料
• 发起人搜索结果仅涵盖 OpenParliament 的索引（sponsorCoverage: "openparliament_index"），不包含参议员；扫描超过 10 页、每页 100 条时会以 sponsor_scan_incomplete 失败

---

canparl_get_bill _工具

• 使用 canparl_search_bills 返回的 billCode 及其 session；返回发起人及其所属团体的 title、众议院／参议院／御准阶段、众议院表决记录（dateTime 是 LEGISinfo 的会议日期时间，并非记录表决的时间）、参议院投票记录、出版物和 statute
• 还会以纯文本返回加拿大议会图书馆的立法 summary 和档案 notes（每个注释链接均保留为 text (href)）、六个阅读阶段的 UTC 时间点，以及相关的 webReferences（新闻稿、背景文件、成本估算说明）；这些 URL 按发布时的内容转交，不会抓取
• 响应超出 24,000 字节预算时，会返回 kind: "outline"，并内嵌 sponsor、statute 和 milestones，同时列出各部分：sponsor、stages.house、stages.senate、stages.royalAssent、divisions、senateVoteDetails、publications、statute、summary.en、summary.fr、notes.en、notes.fr、milestones 和 webReferences；重新调用时传入 section，并通过 pagination.nextOffset 使用 offset 和 limit（1–100，默认为 20；值最高为 10,000 时会截断为 100，并显示提示）为集合分页
• 分页时每页包含完整记录；若不可拆分的记录或语言部分超出预算，则会完整返回并附带 disclosure；null、空内容和超出末尾范围的部分各自保持不同状态

---

canparl_search_members _工具

• 现任成员名册：按 name 和 riding 子字符串、province（邮政编码或全名）及 party 搜索；limit 为 1–100（默认为 25；值最高为 10,000 时会截断为 100，并显示提示），并返回精确的筛选后 total
• includeFormer: true 会改为搜索 OpenParliament 的历史姓名索引：一个词可匹配姓氏，多个词可匹配完整的已记录姓名。此时不接受地理位置和党派筛选，结果行可能仅包含姓名和 slug，且 total 为 null
• 将 detailLookup 原样传给 canparl_get_member：现任成员行包含官方 personId，历史成员行包含 OpenParliament slug
• 完整成员行会在达到 24,000 字节响应预算前停止；使用相同筛选条件跟进 pagination.nextOffset。若单行过大，则会完整返回并显示提示

---

canparl_get_member _工具

• 在 detailLookup 中提供且仅提供一个 personId 或 slug；返回个人资料和带日期的 memberships。如果纯数字 slug 与当前 personId 相同，或是 /politicians/<digits>/ 路径或 URL，则按该 personId 读取
• 当前人物交叉索引会验证官方 ID 和记录中的姓名或已公布的别名；如果精确姓名查询返回空页面，则进行范围受限的姓氏查询，以兼容重音符号和中间名首字母，不会猜测 slug
• sponsoredBills（0–5，默认值为 5）和 recentVotes（0–10，默认值为 10）通过 billsOffset 和 votesOffset 独立分页；0 表示跳过该部分，最多为 10,000 的值会限制在上限并附带提示
• 提供一个官方 personId 时，选票按最新到最早的顺序，通过一次请求从官方议员选票信息流中获取，范围为该议员最近的会期或 votesSession，还可按 votesBillCode 缩小范围。ballot 使用 Yes/No/Paired，officialBallot 保留 Yea/Nay/Paired，source 标明信息流；其他议员仍使用 OpenParliament 选票
• 每个活动部分都会报告 available、unavailable 或 not_requested，并提供 failure 元数据；历史记录不可用时绝不会报告为空
• 不会获取个人资料中的 links：绝对 http 或 https URL 会按发布时的原样转发，相对值则以 https://openparliament.ca 为基准解析

---

canparl_search_votes _工具

• 可使用 billCode、result（Agreed To、Negatived、Tie）、documentType、含首尾日期的渥太华日期 dateFrom 和 dateTo，以及 subjectContains；limit 为 1–100（默认值为 25；最多为 10,000 的值会限制在 100 并附带提示），支持偏移分页
• 按从最新到最早的顺序返回，并提供官方统计数和精确筛选后的 total；将 session 和 number 传给 canparl_get_vote
• 完整表决记录行达到 24,000 字节响应预算时会提前停止；使用相同筛选条件继续请求 pagination.nextOffset。单行过大时会完整返回并附带提示

---

canparl_get_vote _工具

• 提供 number 及其 session；ballot（Yea、Nay、Paired；也接受 Yes/No）、personId、party 和 province 仅筛选选票页面；limit 为 1–400（默认值为 30；最多为 10,000 的值会限制在 400 并附带提示），支持偏移分页
• tally、byParty 和 ballotsTotal 涵盖整场表决，ballotsMatched 则涵盖筛选后的集合；如果统计数不一致，tallyMatchesBallots 会标记差异，但不会更改任一计数
• 选票为 Yea、Nay 或 Paired；不会列出未投票者，因此没有选票记录的 personId 会返回空页面
• 页面达到 24,000 字节响应预算时会停止，并返回 truncated 和提示；使用 nextOffset 获取剩余内容

---

canparl_search_speeches _工具

• 必须指定一个范围：politician、billDebated 或 mentionedBill（{ session, code }）、dateFrom 或 dateTo；contains 是字面英文子串，不能单独作为范围。limit 为 1–10（默认值为 5；最多为 10,000 的值会限制在 10 并附带提示），页面达到 24,000 字节响应预算时会停止，并至少完整返回一篇演讲
• politician 接受与 canparl_search_bills 的 sponsor 相同的 slug、路径、URL 或当前 personId 值，并以相同方式解析；appliedFilters.politicianName 会标明所用个人资料
• 每次调用最多扫描 100 个原始候选项：使用相同筛选条件继续请求 nextOffset，直到 exhausted 后再断定没有匹配项；即使如此，结果也仅涵盖 OpenParliament 的索引
• 提供完整英文 content，以及演讲日期对应的党派和选区（不可用时为 null）；substantiveOnly（默认值为 true）会剔除程序性发言，委员会记录则会排除并计入 excludedCommittees

---

canparl_list_reference _工具

• topic：sessions、bill_types、bill_statuses、vote_results、vote_document_types 或 parties；返回完整集合，不分页
• sessions 不接受 session，并会报告每个会期的法案覆盖范围（basic 或 full）和众议院表决记录覆盖范围；其他主题需要指定会期，并将其信息源中的每个值标记为 observed

功能

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

加拿大议会专属功能：

• 官方法案数据覆盖从会期 35-1（1994 年）开始，完整档案从 37-1（2001 年）开始，众议院表决记录从 38-1（2004 年）开始；OpenParliament 的历史姓名索引可追溯至 1994 年
• 法案涵盖两院；议员、表决和发言工具涵盖加拿大众议院。历史记录中缺失的字段保留为 null
• 会期可使用 "45-1" 或 { "parliament": 45, "session": 1 }；未指定会期时，默认从当前官方法案信息源解析，但发言法案范围除外
• 共享信息源请求节流、短时内存缓存、重试，以及 50 秒的工具截止时间。OpenParliament 请求会按顺序发送，两次请求的启动间隔为两秒，因此议员提案法案和 OpenParliament 表决记录可能需要数十秒
• 官方信息源返回 HTTP 403 拒绝访问时，会报错 upstream_blocked，并提供信息源名称及稍后重试该信息源的建议；响应 HTML 不会纳入错误信息，官方数据绝不会由其他信息源的数据替代

便于 Agent 使用的输出：

• 来源信息：每次成功检索都会提供 source、url、原始 retrievedAt 和 cached
• 明确的数据覆盖范围：规范化的 appliedFilters、续传字段、提示信息和类型化失败原因，可区分无匹配项与数据不可用或不完整
• 双重呈现：每个 structuredContent 值（包括完整的信息源文本）也会以 Markdown 形式呈现在 content[] 中

加拿大议会研究指南将法案、表决、议员和 Hansard 记录关联起来，并说明得出历史结论所需的证据。该指南随插件安装包、npm、Docker 和桌面版一同提供，也可通过 MCP 从 skill://canada-parliament-guide/SKILL.md 获取。

开始使用

在 Claude Code 中连接托管服务：

claude mcp add --transport http canada-parliament-mcp-server https://canada-parliament.caseyjhand.com/mcp

或在本地运行：

claude mcp add canada-parliament-mcp-server -- npx -y @cyanheads/canada-parliament-mcp-server

对于其他客户端，请将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "canada-parliament-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/canada-parliament-mcp-server"]
    }
  }
}

无需 API 密钥。可选设置 CANPARL_USER_AGENT，以便上游信息源识别你的部署。如需了解 Docker 或从源码构建，请参阅运行服务。

配置

变量	描述	默认值
CANPARL_USER_AGENT	向上游信息源发送的 HTTP User-Agent。留空时使用默认值；不接受 CR 和 LF。	canada-parliament-mcp-server ([email protected]; https://github.com/cyanheads/canada-parliament-mcp-server)
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
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。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+），并可访问 Internet 上的 parl.ca、ourcommons.ca 和 openparliament.ca。

git clone https://github.com/cyanheads/canada-parliament-mcp-server.git
cd canada-parliament-mcp-server
bun install
cp .env.example .env

• 构建并运行生产版本：

  # 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
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/canada-parliament-mcp-server:latest

该镜像默认使用 HTTP 传输、无状态会话，并将日志写入 /var/log/canada-parliament-mcp-server。若要通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/canada-parliament-mcp-server:latest"]。使用 docker build -t canada-parliament-mcp-server . 在本地构建；默认安装 OpenTelemetry 相关组件，也可通过 --build-arg OTEL_ENABLED=false 将其省略。

项目结构

目录	用途
src/mcp-server/tools/definitions	工具定义（*.tool.ts）、共享 Markdown 渲染器和共享的成员身份对照表。
src/services/legisinfo	LEGISinfo 服务——会话发现、官方法案列表和案卷。
src/services/ourcommons	众议院服务——当前成员名单、表决记录和议员投票 XML。
src/services/openparliament	OpenParliament 服务——历史身份、活动、演讲和成员资格。
src/domain	共享架构、规范化、参考词汇和请求预算。
src/config	使用 Zod 解析并验证服务器专用环境变量。
skills/	为调用这些工具的 Agent 发布的议会研究指南。
tests/	基于上游合成数据的解析器、服务、工具和集成测试。

完整目录树请参阅 docs/tree.md。

开发指南

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

• 处理程序抛出异常，框架负责捕获；仅在转换已知来源故障或保留可选补充信息时捕获异常
• 使用 ctx.log 记录日志，使用 ctx.enrich 添加已应用的筛选条件、总数和通知
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

代码采用 Apache 2.0 许可。议会数据为非官方复刻，来源注明为 Parliament，并在适用时注明 OpenParliament；版权归 Parliament 所有。数据的再利用分别受 Parliament 声明、议长许可、参议院条款和 OpenParliament API 条款约束。该免费、非商业中继服务不代表政府背书，也不意味着数据采用开放数据许可。