eur-lex-mcp-server

---

概述

来自 EUR-Lex 的欧盟立法、CJEU 判例法和条约。搜索文件和判例法，获取全文，解析引文，追踪各法案如何修订和引用彼此，并浏览 EuroVoc 主题词表。

工具

工具	说明
eurlex_search_documents	按类型、日期、EuroVoc 主题、作者机构和生效状态搜索欧盟立法、条约和准备性文件
eurlex_get_document	按 CELEX、ELI 或 work URI 获取法案或案件的元数据（包括 ELI、官方公报引文和生效日期）及全文（HTML、Markdown 或 Formex4 XML），并提供其章节大纲
eurlex_lookup_celex	将 CELEX 编号、ELI URI、ECLI、官方公报引文（Regulation (EU) 2016/679）或官方公报索引（OJ L 119, 4.5.2016, p. 1）解析为其规范 CELLAR work
eurlex_get_cases	按案件编号、法院、案件类型和日期范围搜索 CJEU 和普通法院的判例法
eurlex_get_relations	遍历 CELLAR 关系图——修订、废止、合并、法律依据及据此通过的文件、法案所通过的提案、解释性裁决（按条款）、引文、转置
eurlex_browse_subjects	搜索 EuroVoc 主题词表，将术语解析为概念 URI
eurlex_query_sparql	对 CELLAR 端点执行原始、只读的 SPARQL SELECT 查询

资源

资源	描述
eurlex://document/{celexNumber}	CELLAR 文书的元数据快照
eurlex://document/{celexNumber}/relations	CELLAR 文书的一跳关系摘要

所有资源数据也可通过工具获取。

提示词

提示词	描述
eurlex_comparative_analysis	构建针对某一政策领域的欧盟/美国比较法律分析

技能

技能	描述
eur-lex-guide	供调用工具的 Agent 使用：各类 CELEX、ELI、ECLI 和案件编号格式的来源；在得出某项法案有效、已废止、尚未解释或已终结的结论之前应执行的检查；以及供 eurlex_query_sparql 使用的 CELLAR SPARQL 和 CDM 参考资料

该技能位于 skills/ 中。插件安装包、.mcpb 捆绑包、npm 包和 Docker 镜像均包含该技能，且服务端通过 Skills 扩展（skills/list、skill:// 资源）向 MCP 客户端提供该技能。

---

功能参考

eurlex_search_documents _工具

• 至少指定一个筛选条件：keyword（英文标题，以及 CELEX 编号或片段，例如 2016R0679；仅含字母且不含数字的关键词，例如 R(01)，会扫描所有 CELEX，可能需要几十秒；不搜索正文）、document_type（REG、DIR、DEC、TREATY、JUDG、OPIN_AG、PROP、REC）、date_from/date_to、eurovoc_concept（来自 eurlex_browse_subjects）、author_institution 或 in_force（true/false；false 涵盖已废止、已失效和尚未生效的法案）
• 通过 offset/limit 分页，每页最多 100 条（较大的 limit 会按 100 条处理，并在 limit_clamp 中报告）；结果按时间倒序排列；每一行都会标记 is_consolidated 和 is_corrigendum，勘误和合并文本仅在指定 include_corrigenda 和 include_consolidated 时显示。分页会在第 10,000 行停止：最后一页不包含 next_offset，并提供 notice，说明继续查询所需的 date_from/date_to 时间范围
• 没有匹配项时，返回带有如何放宽筛选条件说明的空页面；类型化错误：no_filters、invalid_date_range、invalid_author_institution、invalid_keyword（不含字母或数字）、offset_past_window（offset 为 10,000 或更大）
• author_institution 可匹配英文机构名称和 eurlex_get_document 返回的国家法院名称，例如 European Parliament 或 Supremo Tribunal de Justiça；可搭配或不搭配日期范围使用

---

eurlex_get_document _工具

• celex_number、eli_uri 或 work_uri 必须且只能提供一个（接受粘贴形式，例如带 CELEX: 前缀或 EUR-Lex URL）；正文可使用 24 种 EUR-Lex 语言中的 html（默认）、markdown 或 xml（Formex4），若无对应语言则回退到英语。判例还包含 ecli、formation、referring_court、subject_matter 和 case_reference；合并文本会将其基础法案标记为 base_act_celex
• content_mode 可设为 "paged"（默认）、"full" 或 "metadata_only"；每次调用最多返回 100,000 个字符（更大的 limit 会通过 limit_clamp 报告），并提供 content_chars_total/has_more 以便分页；outline: true 会列出带偏移量的标题，select（例如 { articles: "1,5,17" }）只返回指定章节。对于判决和 AG 意见，提纲会列出章节标题，select: { operative_part: true } 则只返回裁决部分
• is_superseded 会标记是否有更新的合并版本（current_consolidated_celex、consolidated_as_of），而 resolve: "current_consolidated" 会返回该版本；in_force: false 时，如果 CELLAR 有记录，则会附带 repealed_by、end_of_validity 或 entry_into_force。类型化错误：invalid_identifier_args、not_found、content_challenge（WAF 机器人挑战页面取代了正文）
• 引用事实（CELLAR 未记录时不提供）：eli（合并文本保留其自身在对应时间点的 ELI）；oj_reference，即《官方公报》引用（OJ L 119, 4.5.2016, p. 1–88；1968 年之前不带系列字母，类别字母按 OJ L 42I 的形式显示，逐项公布的法案采用 OJ L, 2024/1689, 12.7.2024 形式）；页码取自英文版，或 1973 年以前的原文版本；重印法案则采用最早一期的引用；dates_of_effect，每个已记录日期均为 { date, type? }，其中 type 为 entry_into_force、application、partial_application、provisional_application、takes_effect、takes_partial_effect 之一；以及指令的 transposition_deadlines。对于尚未生效的法案，entry_into_force 仍表示未来的生效日期。合并文本会报告其基础法案的 oj_reference、dates_of_effect 和 transposition_deadlines
• 可用的旧版 HTML/Markdown 正文可能带有 content_omissions: { tables }：缺失表格标记按完整来源统计，包括返回窗口之外的内容。分页无法取回这些表格。若成功发现，alternative_representations 会列出所提供作品和语言对应的 PDF 流；XML 是否可用则相互独立。仅元数据调用不会检查来源遗漏
• 国家实施措施会带有稀疏的 national_measure 引用字段：journal、number、pages、publication_date 和 notification_date，仅元数据调用也会提供这些字段。编号和页码保留来源中的写法；公布日期、通知日期和文件日期彼此不同。正文不可用时，可使用公报引用来检索；不会推断国家门户 URL，且通知并不能证明已完成全部转置

eurlex_lookup_celex _工具

• CELEX 编号、ELI URI、ECLI，或注明法案类型和年份的《官方公报》（OJ）引文（Regulation (EU) 2016/679、Directive 95/46/EC，也可以附上括号中的 OJ 引用，例如 Directive 95/46/EC (OJ L 281, 23.11.1995, p. 31)）；粘贴的格式（CELEX: 前缀、EUR-Lex 页面 URL、带或不带方案或语言段的 ELI）会经过规范化，并回显在 celex_number 中。没有法案类型（95/46/EC）或年份（Regulation No 17）的引文无法解析
• OJ 引用会解析为从所引页面开始的法案：期号、出版日期和首页（OJ L 281, 23.11.1995, p. 31，也支持 of 23.11.1995、页码范围、如 OJ L 42I 的类别字母、OJ C，以及 1968 年之前不带系列的格式 OJ 13, 21.2.1962, p. 204/62）；年份在前的格式 OJ 1995 L 281, p. 31 和 OJ 1995 L 281/31；以及逐项法案格式 OJ L, 2024/1689, 12.7.2024 和 OJ C, C/2024/2664, 29.4.2024。所引日期必须与期号的出版日期一致。页码会按英文版匹配；如果该期没有英文页码，则会按 1973 年之前的任意语言版本匹配。缺少年份或首页的引用（OJ L 281、OJ L 119/1）无法解析。仅在 auto 模式下识别
• identifier_type 会自动检测格式或设置格式；当无法通过自动检测对输入进行分类时（包括缺少年份或首页的 OJ 引用），会触发 ambiguous_identifier。案件编号（C-131/12）会返回 found: false，并提供指向 eurlex_get_cases 的 notice
• 返回作品 URI、已确认的 CELEX 编号、资源类型、日期和案件的 ECLI；对于格式正确但未匹配到任何作品的标识符、日期或页码均无匹配结果的 OJ 引用，以及首页对应多项法案的 OJ 引用，返回 found: false 和 notice（notice 会列出每项法案的 CELEX 编号）

---

eurlex_get_cases _工具

• 筛选条件：case_number（C-131/12、T-22/20、F-12/05，或 1989 年之前的 26/62；会检索该编号下登记的所有判决、裁定和 AG 意见）、court（CJEU 或 GC）、case_type（judgment、order、ag_opinion）、keyword（英文标题，以及 CELEX 编号或其片段，例如 2013CJ0131）和 date_from/date_to；默认仅返回主要记录，只有在 include_derivative 中加入通知、摘要、概要和勘误
• 可通过 offset/limit 分页，每页最多 100 条（更大的 limit 会按 100 条返回，并在 limit_clamp 中报告）；按时间从新到旧排序。每个案件都包含其有记录的 ECLI，以及 formation、advocate_general、display_title、parties、referring_court、subject_matter 和 case_reference；只有当这些字段未包含标题的部分内容时，才会返回原始 title。分页在第 10,000 条记录处停止：最后一页不含 next_offset，并带有 notice，说明继续结果超出该页的 date_from/date_to 时间范围
• 无匹配项时会返回空页，并提供如何放宽筛选条件的 notice；类型化错误：invalid_case_number、invalid_date_range、invalid_keyword（不含字母或数字）、offset_past_window（offset 为 10,000 或更大）
• case_type: "ag_opinion" 包含 Advocate General 意见（OPIN_AG）和观点（VIEW_AG）；resource_type 用于区分 AG Opinion 和 AG View

---

eurlex_get_relations _工具

• celex_number 和 work_uri 必须且只能提供其中一个；relation_types 可缩小范围至 cites、amends、amended_by、repeals、repealed_by、implicitly_repeals、implicitly_repealed_by、legal_basis、basis_for、interprets、interpreted_by、consolidated_version、national_transposition、adopts、adopted_by 中的任意类型（省略则包含全部 15 种）
• basis_for 列出将该法案列为法律依据的文件；interpreted_by 列出解释该法案的 CJEU 和 General Court 裁决，interprets 则列出裁决所解释的内容；adopts 列出某法案采纳的文件（通常是其委员会提案），adopted_by 则列出采纳某文件的法案。member_states 可将 national_transposition 限定为指定成员国（ISO 3166-1 alpha-3 或两字母代码，返回时统一为 alpha-3）；未使用 national_transposition 却使用此参数会报错 member_states_not_applicable
• article 可将 interpreted_by 限定为裁决记录中涉及该法案某一条的条文（17、6a、Article 17、Art. 17，不区分大小写；空白值会被省略；段落、范围或罗马数字不予接受）。它会匹配任意层级，并忽略前导零；字母也会匹配其拉丁序数（28c 可匹配 Article 28 quater）；如 notice 所述，对于 CELLAR 未记录条文的裁决，将不予列出；返回的 article 为规范化形式。未使用 interpreted_by 却使用此参数会报错 article_not_applicable
• 修正、废止、解释和采纳关系的行包含 provisions，即 CELLAR 记录的该关系所指向的条文，使用紧凑代码（A17P1LC 表示 Article 17(1)(c)）或权限标记代码（AR 43 PA 4）；未包含该字段的行表示没有记录条文，这并不意味着该关系涉及整部法案。如果某页在深度为 1 时仍无法在预算范围内容纳其所有条文，则会从最大项开始整项省略，并在每行报告省略数量 provisions_withheld；如 CELLAR 条文查询失败，则返回不含条文的行，并在 notice 中列明
• 单跳查询，按关系类型和方向分别分页，使用 offset/limit（最多 100，默认为 100；更大的 limit 会在 limit_clamp 中报告），按时间从新到旧排列。每种类型和方向最多分页至第 10,000 行，之后会通过 notice 提供可直接运行的查询，将较早的文件转至 eurlex_query_sparql
• 每个完整响应各自按 64,000 UTF-8 字节预算计算，包括 JSON 和补充信息。超出大小的页面会保留能容纳的最大共同类型／方向深度，并保留完整行和标题；notice 会给出请求和实际采用的限制，以及省略的行数。使用 next_offset（当前 offset 加上实际采用的深度）继续查询。深度为 1 的页面即使超过预算也会完整返回，并附带说明。符合预算的页面保持不变；省略 relation_types 等同于列出全部 15 种类型
• 每种关系均包含 relation_type、direction（outgoing/incoming）、related_work_uri，以及已知时的 related_celex_number、related_date、related_title（仅英文）和 national_transposition 行中的 related_member_state；empty_relation_types 用于区分「无此类型的关系」和「已分页略过」。类型化错误：invalid_identifier_args、member_states_not_applicable、article_not_applicable、not_found、offset_past_window

---

eurlex_browse_subjects _工具

• 匹配 EuroVoc 的首选标签和替代标签，因此常见同义词也能解析到对应概念；支持任意 EU 官方 language（默认为英语）；使用 offset/limit 分页（最多 50；更大的 limit 将按 50 提供，并在 limit_clamp 中报告），最多至第 10,000 行（超过范围时返回 offset_past_window）
• 返回概念 URI、首选标签、代码、上位（父级）标签，以及匹配时对应的替代标签；无匹配结果时返回空页面并附带 notice
• 完全匹配的标签优先，其次是标签或单词开头匹配，最后是其他子串匹配，因此 "AI" 会优先显示人工智能

eurlex_query_sparql _工具

• 仅支持只读 SELECT（拒绝更新形式以及 ASK/CONSTRUCT/DESCRIBE）；自动注入 cdm:、skos: 和 xsd: 前缀；可选 timeout_hint（1000–55000 ms）
• 结果数量上限为 MAX_SPARQL_RESULTS（默认值为 100）；结果被截断时，notice 会提示添加 ORDER BY，并使用更高的 OFFSET 重复查询，最多到第 10,000 行。未加类型的字符串字面量查询结果为零行时，notice 会提示为其指定类型（^^xsd:string；ELI 使用 ^^xsd:anyURI）或添加语言标签
• 类型化错误：not_read_only（SPARQL 更新）、unsupported_query_form（ASK、CONSTRUCT、DESCRIBE 或没有 SELECT）、sparql_error、sparql_timeout

---

eurlex://document/{celexNumber} _资源

• 以 application/json 格式提供元数据快照，包括资源类型、作者机构（标签与 eurlex_get_document 中的相同）、总法律顾问、日期、英文标题、生效状态、eli、oj_reference、dates_of_effect、transposition_deadlines、法律依据、EuroVoc 主题（四个引文字段与 eurlex_get_document 中的相同）；合并文本保留其自身的 eli，添加 base_act_celex，并从该法案读取作者、生效状态、oj_reference、dates_of_effect、transposition_deadlines、法律依据和主题
• celexNumber 来自 eurlex_search_documents、eurlex_get_cases 或 eurlex_lookup_celex

---

eurlex://document/{celexNumber}/relations _资源

• 对全部 15 种 eurlex_get_relations 类型提供一跳关系摘要，不含 provisions；每个相关作品在有对应信息时均包含其 related_date 和英文 related_title；每种关系类型和方向最多 25 条（保留最新条目）
• 存在更多关系时，提供 truncated 和指向 eurlex_get_relations 的 continuation 指针

---

eurlex_comparative_analysis _提示词

• 参数：必需的 domain；可选的 focus，会并入与其匹配的分析维度，或作为单独章节添加
• 返回一份研究计划，将领域改述为欧盟法律用语（“反垄断” → “竞争法”），按顺序调用欧盟侧的 eurlex_browse_subjects → eurlex_search_documents → eurlex_get_document → eurlex_get_relations，以及美国侧的 courtlistener_search_opinions，并附上六维分析框架

功能

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

EUR-Lex 专属：

• 无需 API 密钥——CELLAR SPARQL 和 EUR-Lex REST 内容端点均可公开访问
• SPARQL 使用内置的 CDM 前缀声明，通过 POST 发送；服务端强制执行 LIMIT（最大值为 100），以防止 Virtuoso 超时
• 法案正文通过 CELLAR 内容协商获取；HTML 按原样返回，多部分 Formex4 XML 会合并为一个文档，Markdown 则在服务端转换
• 语法、编译和排序窗口错误会立即以 sparql_error 返回（排序窗口错误 SR353 提示降低 OFFSET 或缩小查询范围），超时则以 sparql_timeout 返回；这两类错误均不会重试。网关页面和其他暂时性故障会在该调用共享的查询预算（SPARQL_QUERY_TIMEOUT_MS）内重试；若预算不足以完成重试阶梯，则报告最后一次尝试自身的错误
• 请求的译文不可用时自动回退到英语，并报告请求语言和实际使用的语言

便于 Agent 使用的输出：

• 服务器级说明中包含 EuroVoc 前置指引——提示 Agent 在进行按概念筛选的搜索前先调用 eurlex_browse_subjects
• eurlex_lookup_celex 会预先确认 CELEX/ELI/ECLI 是否存在，避免后续获取文档或关系时出错
• content_status、content_unavailability_reason 以及请求语言/实际使用语言字段，无需解析字符串即可区分已跳过、可用、缺失、上游故障和内容不完整等情况
• 每个工具的错误契约都包含带类型的 reason 代码，使 Agent 能以编程方式按结果分支处理

---

开始使用

无需安装，直接连接到托管实例：

claude mcp add --transport http eur-lex-mcp-server https://eur-lex.caseyjhand.com/mcp

或者在本地运行：

claude mcp add eur-lex-mcp-server -- npx -y @cyanheads/eur-lex-mcp-server

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

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

无需 API 密钥。有关 Docker 或从源代码构建的信息，请参阅运行服务。

---

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。

变量	描述	默认值
CELLAR_SPARQL_ENDPOINT	CELLAR SPARQL 端点 URL 覆盖值（例如，用于本地 Virtuoso 镜像）。	http://publications.europa.eu/webapi/rdf/sparql
EURLEX_CONTENT_BASE_URL	EU Publications Office CELLAR 内容解析器基础 URL 覆盖值。	http://publications.europa.eu
SPARQL_QUERY_TIMEOUT_MS	客户端超时时间（毫秒），为 1 至 2147483647 之间的整数：一次调用的 CELLAR 查询共享的预算（串联多个查询的调用只消耗一次，而非每个查询各消耗一次），也是任何单个查询的上限；EUR-Lex 内容获取会使用独立的同长度超时，不计入共享预算。	55000
MAX_SPARQL_RESULTS	所有生成的 SPARQL 查询中 LIMIT 的强制上限。	100
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_SESSION_MODE	会话处理方式：stateful、stateless 或 auto（auto 会解析为 stateful）。	stateless
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录失败工具调用的参数和结果，按键名进行脱敏（自由格式的值不会脱敏），并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节以内（默认值为 16384）。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选覆盖值列表请参阅 .env.example。

---

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。

• 克隆并安装：

  git clone https://github.com/cyanheads/eur-lex-mcp-server.git
  cd eur-lex-mcp-server && bun install
  cp .env.example .env   # optional: every variable has a default
  

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http   # listens at http://localhost:3010/mcp
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/eur-lex-mcp-server:latest

该镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/eur-lex-mcp-server。若要通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/eur-lex-mcp-server:latest"]。若要在本地构建，请运行 docker build -t eur-lex-mcp-server .，然后运行 docker run --rm -p 3010:3010 eur-lex-mcp-server；默认会安装 OpenTelemetry 对等依赖——使用 --build-arg OTEL_ENABLED=false 构建可省略这些依赖。

---

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具、资源、提示词和已发布的技能；初始化服务。
src/config	使用 Zod 解析并验证特定于服务的环境变量。
src/services/cellar-sparql	CELLAR SPARQL 服务——POST 客户端、绑定映射器、LIMIT 强制执行、CDM PREFIX 声明。
src/services/eurlex-content	CELLAR 内容服务——针对 /resource/celex/{CELEX} 的内容协商 GET 客户端（Accept / Accept-Language），支持英语语言回退，并在进程内缓存已提供的正文，以便翻页浏览某项法案时只需获取一次。
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖文档搜索、检索、决议、判例法、关系、EuroVoc 和原始 SPARQL 的七种工具。
src/mcp-server/resources	资源定义（*.resource.ts）。元数据和关系资源。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。比较分析提示词。
skills/	发布给调用这些工具的 Agent 的 Agent Skills（eur-lex-guide）。
tests/	与 src/ 结构对应的单元测试和集成测试。

---

开发指南

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

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 进行租户级存储
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失字段

---

贡献

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

bun run devcheck
bun run test

---

许可证

Apache-2.0 — 详情请参阅 LICENSE。