eu-parliament-mcp-server

---

概览

欧洲议会记录来自开放数据 API：探索立法程序、追踪相关证据、查找欧洲议会议员、查看全体会议的决定和投票者，以及获取文件、演讲和质询的元数据。可作为 stdio 进程或本地 Streamable HTTP 服务运行。无需 API 密钥。

工具

工具	说明
euparl_list_reference	查找筛选代码、标识符格式、数据覆盖范围、委员会和政治团体
euparl_list_procedures	按类型列出程序参考信息
euparl_get_procedure	查看程序标识、阶段、事件、参与者和文件参考信息
euparl_search_documents	搜索已通过的文本、列出委员会／全体会议文件，或获取任意规范文件
euparl_search_speeches	搜索第十届任期的演讲活动，并获取元数据和录音文件链接
euparl_search_meps	在完整的现任或指定任期名单中查找欧洲议会议员
euparl_get_mep	查看议员身份信息和已发布的任职历史
euparl_get_plenary_votes	查找会议、查看决定，并分页获取记录在案或预期的投票者
euparl_list_questions	按年份／类型列出质询，或获取质询及答复参考信息

能力参考

所有列表工具都接受 offset（默认值为 0）、limit（默认值为 20，接受范围为 1–1000，实际最大值为 100，并会显示提示）和 language（默认值为 en，须为 24 个欧盟语言代码之一）。请遵循 page.next_offset；对于本地集合，还需传入返回的 page.snapshot。snapshot_changed 错误要求从偏移量 0 开始重新查询，且不传入快照。本地快照会在重新查询时检测变更；不会保留历史数据。

本地化文本会标明其实际来源语言；如使用回退语言，也会予以说明，且文本不会被翻译。缺少详情时通常返回 found: false；空列表会成功返回并附带指引。丰富决策查询则会返回 decision_not_found。

euparl_list_reference _工具

• 必填参数 topic：committees、political_groups、procedure_types、document_types、question_types、activity_types、mep_filters、identifiers 或 coverage
• 委员会和政治团体是现行的法人机构；组织标识符不代表可用的筛选代码。参考页面无需快照

---

euparl_list_procedures _工具

• 可选参数 process_type，取值来自 euparl_list_reference；不支持关键字、年份、委员会或阶段筛选
• 稀疏记录包含 procedure_id、来源 URL 和可用的参考信息／类型；使用 euparl_get_procedure 获取标题、阶段和参与者

---

euparl_get_procedure _工具

• 必填参数 procedure_id 接受 YYYY-NNNN、YYYY/NNNN(TYPE)、可选字母后缀、已知路径前缀或完整的公开程序 URI
• section: "overview" 返回标量元数据和集合计数；events、participants 和 documents 可使用快照对一个集合分页
• 历史参与者群组会保留其历史状态。请在 get 模式下使用 euparl_search_documents 查询文档 ID

---

euparl_search_documents _工具

• mode: "search" 默认使用 source: "adopted_texts"；只有该类别接受 text、title、会议日期和 related_process_id。已通过文本接受年份和届次；委员会类接受届次，全体会议类接受年份
• work_type 使用 euparl_list_reference 中按类别划分的代码。委员会／全体会议检索不支持关键字筛选
• mode: "get" 必须提供 document_id，且不接受来源、搜索筛选条件和非默认分页参数。程序、演讲、投票、问题和答复中的 ID 均使用此查询
• 详情包含元数据、程序／上级引用，以及所选语言下的所有来源文件链接。若某个细分文档没有文件，请沿 parent_document_ids 查询；不会下载或提取文档正文

---

euparl_search_speeches _工具

• 可按 text、title、person_id、activity_type 或会议日期范围搜索；覆盖范围仅限议会第 10 届任期
• mode: "get" 必须提供 speech_id，且不接受搜索筛选条件和非默认分页参数
• 返回活动元数据和参与者，不含演讲稿。请通过文档 get 查询 document_ids，并沿任何上级引用查找来源文件

---

euparl_search_meps _工具

• 省略 term 时选择当前在任的议员；明确指定 term 时选择第 0–10 届的已发布名册。可选的国家、政治团体和性别代码取自 mep_filters
• name_contains 会在分页前，对完整名册中的所有规范化词元进行匹配，并忽略大小写、变音符号和标点
• 结果使用快照继续分页。国家／团体信息描述所选名册的上下文，而非投票日期时的党派归属

---

euparl_get_mep _工具

• mep_id 接受十进制人员 ID、person/ 前缀或完整的公开人员 URI
• 默认的 section: "overview" 返回身份信息和 membership_count；section: "memberships" 使用快照对已发布的任职历史分页
• 未提供成员资格结束日期并不能证明其目前仍具成员资格

---

euparl_get_plenary_votes _工具

• mode: "sittings" 需要 year；默认的 decisions 模式需要 sitting_id，并分页返回精简摘要。开会 ID 可使用真实的 YYYY-MM-DD 日期、MTG-PL- 格式、已知事件前缀或公开 URI
• mode: "decision" 需要开会 ID 和决议 ID，并返回一条完整记录，包含完整标签、说明和文档引用；该模式不支持分页和快照
• mode: "voters" 还需要 position：favor、against、abstention、intended_favor、intended_against 或 intended_abstention。决议和投票者位置分别分页，并支持快照
• resolve_names: true 仅适用于投票者模式，且需要 roster_term（0–10）；无法解析的 ID 仍会保留在输出中。姓名来自该届已公布的名册，不包含投票日期时的隶属关系
• 已公布的计票结果与投票者数组中的计数分别保留。available: false 表示数组缺失；已公布的空数组则为 available: true。拟议更正不会替代记录在案的投票

---

euparl_list_questions _工具

• 默认的 mode: "list" 接受 year 和 work_type；不支持按关键词、作者或收件人搜索
• mode: "get" 需要 question_id：可使用规范工作 ID、已知文档前缀／公开 URI，或人工引用格式（如 E-000001/2025，也支持 P/O 前缀）。可选的 term 可直接解析引用；若省略，则会搜索引用年份内的所有记录，并要求只有一个精确匹配项
• Get 模式不接受列表筛选条件和非默认分页设置。详情会返回元数据、源文件和已公布的答复引用；answers 为空并不能证明该问题尚未得到答复

功能

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

欧洲议会专属功能：

• 无需密钥即可访问议会的公开 JSON-LD 记录，并通过规范标识符关联发现结果、详情和来源证据
• 共享请求节流、有限重试，以及一个覆盖数据获取和队列等待的 40 秒操作时限
• 完整名册姓名筛选；程序证据、成员资格历史、决议摘要和投票者数据分别分页

便于 Agent 使用的输出：

• 来源 URL、实际语言标签、规范化筛选条件、可用时提供的精确总数，以及后续操作指引
• 缺失字段会保留其不确定性；已公布的零值、缺失数组和历史隶属关系均分别呈现
• content[] 和 structuredContent 中包含匹配的数据，并提供可用的来源链接和类型化错误原因

数据来源：European Parliament Open Data，依据 CC BY 4.0 许可。本服务会规范化标识符和记录结构。议会记录并不能证明已制定法律信息完整无缺，也不能证明某位成员的终身投票历史完整无缺。

开始使用

自托管／本地部署

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

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

或使用 npx（无需 Bun）：

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

或使用 Docker：

{
  "mcpServers": {
    "eu-parliament-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/eu-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/eu-parliament-mcp-server.git

2. 进入目录：

cd eu-parliament-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env to override framework settings as needed

配置

变量	描述	默认值
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。

运行服务

本地开发

• 构建并运行生产版本：

  # 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/mcp-server/tools/utils	共享模式、无损渲染和数据增强。
src/services/eu-parliament	JSON-LD 客户端、边缘模式、参考代码、规范化和领域工作流。
tests/	单元测试和集成测试，结构与 src/ 相对应。
docs/	设计约定和生成的项目目录树。

开发指南

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

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

贡献

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

bun run devcheck
bun run test

许可证

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