uk-parliament-mcp-server

---

概述

通过英国议会官方的法案、议员、下议院和上议院投票、Hansard、书面质询及委员会 API，获取威斯敏斯特记录。搜索议会事务，检索指定记录和来源链接，并通过各自独立的标识符追踪议员、法案、投票、答复和委员会证据。可作为 stdio 进程或本地 Streamable HTTP 服务运行；无需 API 密钥。

工具

工具	描述
ukparl_lookup_reference	查询筛选 ID、标识符命名空间和历史覆盖范围说明
ukparl_search_bills	按标题、议院、会期、提案人、阶段和法案类型搜索法案摘要
ukparl_get_bill	获取法案详情、阶段、出版物、修正案和拉锯式议案
ukparl_search_members	查找现任和前任下议院议员及贵族院议员，包括按日期搜索议员资格
ukparl_get_member	获取个人资料、职务、委员会席位、官方联系方式、利益申报和投票历史
ukparl_search_divisions	搜索指定议院的分组投票，并查看元数据、投票者和党派统计
ukparl_search_hansard	搜索口头发言；如提供完整来源文本，也会一并显示
ukparl_search_questions	搜索质询和答复预览，或获取完整质询详情
ukparl_get_committee	查找委员会并获取其成员、事务和出版物元数据

能力参考

ukparl_lookup_reference _工具

• topic：identifiers、coverage、bill_stages、bill_types、parties、departments 或 answering_bodies；实时目录默认返回 10 行，最多 20 行，可选用 nameContains 按 AND 逻辑筛选词语
• 仅 parties 需要 house；该目录涵盖所选 House 中的现任党派，不包含所有历史党派。静态指南不接受 House 或名称筛选条件
• 标识符指南区分参考用 stageId 与法案专属 billStageId、按 House 区分的 division ID、Questions API ID 与 UIN，以及委员会人员 ID 与 Members API ID

---

ukparl_search_bills _工具

• 可选参数：query、house、sessionId、memberId、stageIds 和 billTypeIds；每个 ID 数组最多接受 20 个条目。默认返回 10 项法案，最多 20 项
• 结果为 detailLevel: "summary"，包含 billId、来源信息和集合续页信息；不会推断当前会期范围。使用 ukparl_lookup_reference 解析参考筛选条件

---

ukparl_get_bill _工具

• 必需参数：billId；section 默认为 overview，也可选择 stages、stage、publications、amendments、amendment、motions 或 motion。集合默认返回 20 条记录，最多 50 条
• 阶段、修正案和动议的选择需要使用 stages 中的法案专属 billStageId；获取单条修正案或动议还需要父集合中的 itemId（修正案使用 amendmentId，动议使用 motion.id）。修正案和动议列表为摘要；单项选择器会获取完整文本
• 找不到实体时返回 found: false 和 guidance。legislationHandoff.status 为 authoritative_link、not_enacted 或 unavailable；只有实际提供的 legislation.gov.uk 链接才会建立法规交接

---

ukparl_search_members _工具

• 可选参数：name、constituency（来源中的地点文本）、partyId 和 house；currentOnly 默认为 false，包含现任和前任成员。默认返回 10 行，最多 20 行
• asOf 用于指定真实的 YYYY-MM-DD 日期所对应的成员任职情况，并且只接受 name 和分页参数；返回的最新个人资料字段并非历史快照
• 摘要结果包含供 ukparl_get_member 使用的 memberId、source 和 page；未知的来源字段会省略或设为 null

---

ukparl_get_member _工具

• 必需参数：memberId；section 可为 profile（默认）、roles、committee_seats、contact、interests 或 voting。若 roles 未提供 category，则返回可用性概要；选择返回的类别即可获取完整任职时期
• interests 和 voting 需要 house，其他部分不需要。局部历史记录默认返回 20 行，最多 50 行；投票使用原生 20 行分页，不受 limit 影响
• found 和 guidance 用于区分成员不存在与来源集合不可用。利益关系树和委员会关系保留来源指针；投票信息保留记录的表决阵营和计票员事实，不会推断弃权或终身参与情况

---

ukparl_search_divisions _工具

• 必需参数：house：commons 或 lords；mode：search（默认）、detail、voters 或 party_totals。搜索接受 query、memberId 以及包含首尾日期的 startDate / endDate；默认返回 5 项 division，最多 10 项
• 其他模式需要使用同一 House 中的 divisionId。选民列表默认返回 20 行，最多 50 行，保留来源中的精确 party 标签和 lobby：Commons 使用 aye、no、not_recorded；Lords 使用 content、not_content
• 详情保留标题计数和计票员身份；partyTotals 分别统计列出的非计票员和计票员。not_recorded 表示来源列表中的记录，绝不表示弃权；成员搜索包含计票员参与情况

ukparl_search_hansard _工具

• 可选参数：query、memberId、house、包含边界的 startDate / endDate，以及数值型 debateSectionId；默认返回 5 条发言，最多 20 条。日期格式为 YYYY-MM-DD，不会推断时间范围
• detailLevel: "complete" 包含完整的原始发言文本，包括 HTML；summary 表示来源仅提供了预览。按章节筛选并不能保证获得完整的辩论记录
• coverage 会报告历史数据的限制，包括 2004–2006 年网站警告；结果为空并不能证明没有发生过辩论。超时后请缩小日期范围；如需了解档案指南，请使用 ukparl_lookup_reference，并设置 topic: "coverage"

---

ukparl_search_questions _工具

• mode: "search"（默认）接受 query、memberId、house、最多 20 个 answeringBodyIds、answered，以及包含边界的 tabledFrom / tabledTo / answeredFrom / answeredTo 日期（YYYY-MM-DD）。默认返回 10 条预览，最多 20 条
• 搜索包含所有会期和已撤回的问题；省略 answered 时会包含两种状态。mode: "detail" 仅需提供返回的 questionId，即可获取完整的问题和答案 HTML、更正内容及附件元数据；UIN 不是 questionId
• 结果会区分 detailLevel: "summary" 和 "complete"；未找到详情时会返回 found: false 和 guidance。附件仅提供链接和元数据，不会下载文件

---

ukparl_get_committee _工具

• mode: "search"（默认）接受 query 和 house（commons、lords、joint），默认返回 10 条，最多 20 条。detail、members、inquiries 和 publications 需要提供 committeeId；嵌套集合默认返回 20 条，最多 50 条
• inquiry 需要提供 businessId；publication 需要提供 publicationId。businessId 也可用于筛选 publications。membership 用于在 members 模式下选择 all（默认）、current 或 former；inquiries/publications 中的 query 至少需要两个字符
• inquiries 包含所有委员会事务类型，并通过 isInquiry 标注。记录会保留带类型的实体和 sourcePath 关系；publications 返回证据/报告元数据和文档链接，但不会下载文件或提取文本

功能特性

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

英国议会专属功能：

• 无需密钥，只读访问七个官方威斯敏斯特 API 来源；权力下放议会不在范围内
• 标识符命名空间彼此独立，且需明确选择来源；不会推断当前会期或日期范围
• 各来源共享背压控制、有限次数的重试，以及适用于相关请求的 45 秒调用期限
• 历史数据覆盖范围因来源而异：Hansard 档案始于 1803 年 11 月 22 日，Spoken API 的最早日期未知，且不会自动回退到历史档案

便于 Agent 使用的输出：

• 来源信息 — 来源记录附带来源 API、请求 URL、检索时间戳和许可链接；applied 会报告实际生效的选择项和限制
• 按完整记录分页 — page.returned、hasMore 和 nextCursor 描述实际输出的记录，只有已知时才提供 total。使用游标时，请重复使用相同的筛选条件和实际生效的限制
• 无损处理大型记录 — delivery: "full" | "outline" | "fragment" 用于区分完整载荷与 contentPage 后续内容。重复使用原始工具输入及每个 contentCursor，遍历所有大纲条目和后续内容；拼接连续片段后再一次性解码 JSON，并在推进 collectionPage 前重建所选记录
• 明确的恢复方式 — invalid_cursor 表示需要重新开始选择；source_changed 表示上游修订后需要重新开始检索内容。搜索预览、缺失记录和不可用集合各自明确区分

开始使用

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

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

或使用 npx（无需 Bun）：

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

或使用 Docker：

{
  "mcpServers": {
    "uk-parliament-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/uk-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 的互联网连接；无需 API 密钥。

安装

1. 克隆仓库：

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

2. 进入目录：

cd uk-parliament-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

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

配置

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的初始端口；发生端口冲突并重试后，启动日志会报告实际绑定的端口。	3010
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP MCP 端点。	/mcp
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/mcp-server/tools/definitions	九个工具定义（*.tool.ts）。
src/services/parliament-http	固定来源的传输、来源信息、游标和无损内容交付。
src/services/bills	法案搜索、审查记录、出版物和参考目录。
src/services/members	议员发现、个人资料、传记、利益和投票历史。
src/services/divisions	下议院／上议院分组表决元数据和记录的投票者集合。
src/services/hansard	口头发言搜索和历史覆盖范围元数据。
src/services/questions	书面问题预览及完整的问题／答案记录。
src/services/committees	委员会事务、成员资格、出版物元数据和类型化关系。
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 文件。

在适用情况下，包含根据 Open Parliament Licence v3.0 授权的议会信息。个人数据、议会标志和第三方权利不在授权范围内；请保留来源中的声明，并在重新使用不在授权范围内的材料前确认相关权利。本软件独立开发，不代表议会背书。