eur-lex-mcp-server

<div align="center">
  <h1>@cyanheads/eur-lex-mcp-server</h1>
  <p><b>Search EU legislation, CJEU case law, and treaties; traverse the CELLAR relationship graph; resolve EuroVoc concepts via MCP. STDIO or Streamable HTTP.</b>
  <div>7 Tools • 2 Resources • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.9.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/eur-lex-mcp-server) [![MCP Server](https://img.shields.io/badge/MCP%20Server-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/eur-lex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/eur-lex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/eur-lex-mcp-server/releases/latest/download/eur-lex-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=eur-lex-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZXVyLWxleC1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22eur-lex-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Feur-lex-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://eur-lex.caseyjhand.com/mcp](https://eur-lex.caseyjhand.com/mcp)

</div>

---

## Tools

Seven tools covering EU legal research — document discovery, content retrieval, citation resolution, case law, relationship graph traversal, EuroVoc thesaurus lookup, and raw SPARQL access:

| Tool | Description |
|:-----|:------------|
| `eurlex_search_documents` | Search EU legislation, treaties, and preparatory acts across the CELLAR corpus. Filters by document type, date range, EuroVoc concept, author institution, and in-force status. |
| `eurlex_get_document` | Fetch structured metadata and full text (HTML, Markdown, or Formex4 XML) for a work by CELEX number or ELI URI. |
| `eurlex_lookup_celex` | Resolve an EU legal citation — a CELEX number or an ELI URI — to the canonical CELLAR work. |
| `eurlex_get_cases` | Search CJEU and General Court case law — judgments, orders, and Advocate General opinions — by case number, party name, subject, or date range. |
| `eurlex_get_relations` | Traverse the CELLAR relationship graph: amendment chain, consolidated versions, legal basis, citation network, and national transposition measures. |
| `eurlex_browse_subjects` | Search the EuroVoc multilingual thesaurus to resolve human-readable terms to EuroVoc concept IDs — required before using the `eurovoc_concept` filter in `eurlex_search_documents`. |
| `eurlex_query_sparql` | Execute a raw SPARQL SELECT query against the CELLAR Virtuoso endpoint. Results capped at 100; use only when curated tools don't cover the needed CDM ontology traversal. |

### `eurlex_search_documents`

Search EU legislation, treaties, preparatory acts, and more across the 2.7M+ work CELLAR corpus.

- Keyword search across work titles and CELEX string patterns
- Filter by document type (`REG`, `DIR`, `DEC`, `TREATY`, and more)
- Date range filtering (`date_from`, `date_to`)
- EuroVoc concept filtering — use `eurlex_browse_subjects` first to resolve concept IDs
- Filter to in-force acts only
- Pagination via `offset` and configurable `limit` (max 100)
- Returns CELEX numbers, work URIs, document types, and dates for chaining into `eurlex_get_document`

---

### `eurlex_get_document`

Fetch the notice and full text of an EU legal act.

- Accepts CELEX numbers (e.g., `32016R0679`) or ELI URIs
- Returns structured metadata: title, date, document type, author institution, legal basis, EuroVoc subjects, in-force flag
- Full text in HTML (default), Markdown, or Formex4 XML — `format: "markdown"` converts the act body to clean Markdown server-side (recitals and numbered points as readable text, genuine data tables as GFM)
- Content shaping for large acts: `content_mode` `"paged"` (default) returns a bounded character window (`offset` + `limit`) with `content_chars_total` and `has_more` so you can page to the end; `"full"` returns the whole body in one call; `"metadata_only"` skips the body
- Navigate structure instead of raw offsets: `outline: true` returns the act's chapters, articles, annexes, and recitals as a heading list (each with its character offset), and `select` (e.g. `{ articles: "1,5,17" }`) returns just those sections' text — degrading cleanly to the paging floor for acts with no detectable structure (e.g. case law)
- Supports all 24 official EU languages; defaults to English with automatic fallback when a translation is unavailable
- Older acts and some CJEU judgments may lack English translations

---

### `eurlex_lookup_celex`

Resolve EU legal identifiers to canonical CELLAR works.

- Accepts CELEX numbers and ELI URIs
- Auto-detects format with `identifier_type: "auto"` (default); set explicitly when auto-detection fails
- Returns work URI, confirmed CELEX number, document type, and date — the prerequisite step before `eurlex_get_document` or `eurlex_get_relations`

---

### `eurlex_get_cases`

Search CJEU and General Court case law.

- Case-specific search: case number, keyword, court (`CJEU` or `GC`), and case type (`judgment`, `order`, `ag_opinion`)
- Date range filtering
- Primary records only by default — derivative information notices, abstracts, and summaries are excluded; set `include_derivative` to include them
- Returns case identifier, court, date, document type, and parties
- Distinct from `eurlex_search_documents` — case law (CELEX sector 6) has its own search parameters and practitioner workflows

---

### `eurlex_get_relations`

Traverse the CELLAR relationship graph for a given work.

- Amendment chain (what amends it, what it amends)
- Consolidated versions (the current in-force text)
- Legal basis
- Citation network (`cdm:work_cites_work` in both directions)
- National transposition measures
- Filter to specific relation types or retrieve all at once
- Returns one-hop relations; multi-hop traversal requires multiple calls or `eurlex_query_sparql`

---

### `eurlex_browse_subjects`

Resolve human-readable terms to EuroVoc concept IDs.

- Full-text search across the multilingual EuroVoc thesaurus
- Returns concept URI, preferred label, concept code, and broader/narrower hierarchy hints
- Supports all EU official languages; defaults to English
- Required before using the `eurovoc_concept` filter in `eurlex_search_documents`

---

## Resources and prompts

| Type | Name | Description |
|:-----|:-----|:------------|
| Resource | `eurlex://document/{celexNumber}` | Metadata snapshot for a CELLAR work — type, date, title, author institution, in-force flag |
| Resource | `eurlex://document/{celexNumber}/relations` | Relationship summary for a work: amendment chain, consolidations, legal basis, cited-by count |
| Prompt | `eurlex_comparative_analysis` | Frames a comparative legal analysis across EU and US law for a given policy domain |

All resource data is also reachable via tools. Resources provide stable-URI injectable context for agents that support MCP resources.

---

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Pluggable auth: `none`, `jwt`, `oauth`
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports
- MCP 2026-07-28 support, exact tool-input validation, and structured error envelopes clients can act on

EUR-Lex-specific:

- No API key required — both CELLAR SPARQL and EUR-Lex REST content endpoints are publicly accessible
- `CellarSparqlService` POSTs `application/x-www-form-urlencoded` SPARQL with CDM prefix declarations built in; server-side LIMIT enforcement (max 100) prevents Virtuoso timeout abuse
- `EurLexContentService` fetches act text from the CELLAR content-negotiation resolver (`/resource/celex/{CELEX}` with `Accept` / `Accept-Language` headers); HTML and Formex4 XML pass through, Markdown is converted server-side from the HTML body
- Virtuoso error classification: HTTP 200 with `Virtuoso 37000 Error` body is parsed and re-raised as `ServiceUnavailable` (transient/timeout) or `InvalidParams` (syntax error)
- Language fallback on document fetch: if the requested language is unavailable, retries with English; returns metadata-only with a note when English also fails
- Typed error contracts on every tool — structured `reason` codes let agents branch on outcomes without parsing text

Agent-friendly output:

- EuroVoc prerequisite guidance in server-level instructions — agents are directed to `eurlex_browse_subjects` before attempting concept-filtered searches
- `eurlex_lo