Openlex MCP Server

🇨🇭 Part of the Swiss Public Data MCP Portfolio

⚖️ openlex-mcp

MCP Server for Canton Zurich legislation (ZH-Lex) — full-text search, article extraction, and education law tools for ~970 cantonal laws

🇩🇪 Deutsche Version

---

Overview

openlex-mcp provides AI-native access to the entire legal collection of Canton Zurich (Zürcher Gesetzessammlung). It combines full-text data from HuggingFace with live metadata from the official zh.ch website, storing everything in a local SQLite database with FTS5 full-text indexing for sub-50ms search performance.

Built for the Schulamt (school department) of the City of Zurich, but covers all areas of cantonal law — from tax law to building regulations.

Anchor demo query: "What does the Volksschulgesetz say about parental involvement? Show me Art. 55 VSG and find all articles that mention 'Elternrat'."

---

Features

• ⚖️ 8 tools covering search, retrieval, article extraction, and cache management
• 🔍 FTS5 full-text search across ~970 cantonal laws with BM25 ranking
• 📑 Article extraction — parse individual articles (Art. / §) with paragraph detection
• 🏫 Education law shortcuts — specialized search for LS 412.x series (Volksschulgesetz, Lehrpersonalverordnung, etc.)
• 🌐 Live metadata from zh.ch for current validity status and PDF links
• 💾 Hybrid architecture — cached full-text (HuggingFace) + live metadata (zh.ch)
• 🔓 No API key required — all data under open licenses (CC-BY-SA 4.0)
• ☁️ Dual transport — stdio (Claude Desktop) + Streamable HTTP (cloud)

---

Development Phase

Current phase: Phase 1 — Read-Only. All tools are read-only (readOnlyHint: true); no writes to external systems. See ROADMAP.md for the phase plan and transition gates before any write or multi-agent capability is added.

---

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• Internet connection (for initial data download and live metadata)

---

Installation

# Clone the repository
git clone https://github.com/malkreide/openlex-mcp.git
cd openlex-mcp

# Install
pip install -e .
# or with uv:
uv pip install -e .

---

Quickstart

# stdio (for Claude Desktop)
python -m openlex_mcp.server

# Streamable HTTP — binds to 127.0.0.1:8000 by default (localhost only)
python -m openlex_mcp.server --http --port 8000

Network binding

By default the HTTP transport binds to 127.0.0.1 (localhost only). The host and port are configurable via the MCP_HOST / MCP_PORT environment variables (or the --host / --port CLI flags, which take precedence).

Never bind to 0.0.0.0 outside a container — it exposes the server to your local network (NeighborJack risk). For containerized/cloud deployments set MCP_HOST=0.0.0.0 explicitly; when that happens outside a detected container the server logs a warning.

Try it immediately in Claude Desktop:

"What is the Volksschulgesetz (VSG)?" "Find all Zurich laws about data protection" "Show me Art. 1 of the Volksschulgesetz" "Which education laws mention 'Schulleitung'?"

---

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "openlex": {
      "command": "python",
      "args": ["-m", "openlex_mcp.server"]
    }
  }
}

Or with the installed entry point:

{
  "mcpServers": {
    "openlex": {
      "command": "openlex-mcp"
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cloud Deployment (SSE for browser access)

For use via claude.ai in the browser (e.g. on managed workstations without local software):

Render.com (recommended):

1. Push/fork the repository to GitHub
2. On render.com: New Web Service → connect GitHub repo
3. Set start command: python -m openlex_mcp.server --http --port 8000
4. Set environment variable MCP_HOST=0.0.0.0 so the container is reachable (the code default is 127.0.0.1; Render sets the RENDER env var, so no NeighborJack warning is logged)
5. Set MCP_CORS_ORIGINS=https://claude.ai so the browser can read the Mcp-Session-Id header (comma-separated list; no wildcard — defaults to empty, i.e. no cross-origin access)
6. In claude.ai under Settings → MCP Servers, add: https://your-app.onrender.com/sse

💡 "stdio for the developer laptop, SSE for the browser."

---

Available Tools

Search & Browse

Article Extraction

Metadata & Cache

Key Legal Area Prefixes (LS Numbers)

Example Use Cases

---

Architecture

┌─────────────────┐     ┌──────────────────────────────┐     ┌──────────────────────────┐
│   Claude / AI   │────▶│  OpenLex MCP                 │────▶│  HuggingFace             │
│   (MCP Host)    │◀────│  (MCP Server)                │◀────│  rcds/swiss_legislation   │
└─────────────────┘     │                              │     │  (974 ZH laws, cached)   │
                        │  8 Tools                     │     ├──────────────────────────┤
                        │  SQLite + FTS5 Cache         │────▶│  zh.ch ZH-Lex            │
                        │  Stdio | HTTP                │◀────│  (live metadata + PDFs)  │
                        │                              │     ├──────────────────────────┤
                        │  No authentication required  │     │  LexFind.ch              │
                        └──────────────────────────────┘     │  (links only)            │
                                                             └──────────────────────────┘

Data Source Characteristics

Design Decision: Tools-only (no MCP Resources)

All 8 endpoints are exposed as Tools rather than MCP Resources. Rationale:

• Every lookup is parametric — queries, abbreviations, article numbers vary per call. Static Resources (one URI per document) don't capture this naturally.
• The corpus is 974 laws × many articles — registering each as a Resource URI would create an impractically large resource list.
• MCP Resource templates (zhlex://laws/{sr_number}) are a future consideration for Phase 2 if clients benefit from resource-level caching or subscriptions.

Scaling Constraints

The Streamable-HTTP transport keeps session state in-process (FastMCP default). This has two implications:

• Single-instance only — horizontal scaling (multiple replicas) breaks active sessions because there is no shared session store (Redis, Durable Objects, etc.).
• No sticky-session LB needed today — a single-replica Render deployment naturally routes all requests to one process.

Before scaling beyond one instance: either add a shared session store or configure your edge load balancer to route on the Mcp-Session-Id header with a stick-table and an appropriate TTL.

---

MCP Protocol Version

Update policy

1. When mcp is upgraded (via Dependabot PR), verify the protocol version in the SDK release notes.
2. If the protocol version changes, update MCP_PROTOCOL_VERSION in server.py, regenerate docs/tool-hashes.json (PYTHONPATH=src python scripts/gen_tool_hashes.py --write), and note the change in CHANGELOG.md.
3. Run pytest tests/ -m "not live" to confirm compatibility before merging.

---

Project Structure

openlex-mcp/
├── src/openlex_mcp/
│   ├── __init__.py              # Package
│   ├── __main__.py              # Entry point for python -m
│   ├── server.py                # 8 MCP tool definitions (FastMCP) + Settings
│   ├── responses.py             # Typed structured response envelopes (SDK-002)
│   ├── logging_config.py        # structlog JSON logging setup (OBS-003)
│   ├── net.py                   # SSRF/egress-hardened outbound HTTP
│   ├── api_client.py            # zh.ch HTTP client + metadata extraction
│   ├── data_cache.py            # SQLite + FTS5 cache management
│   └── law_parser.py            # Article extraction from law texts
├── tests/                       # 89 unit tests (parser, cache, net, tools…)
├── scripts/gen_tool_hashes.py   # Tool-definition hash snapshot (SEC-022)
├── docs/                        # network-egress, secret-management, tool-hashes
├── .github/workflows/ci.yml     # GitHub Actions (Python 3.11/3.12/3.13)
├── .github/dependabot.yml       # Weekly dependency PRs (ARCH-012)
├── Dockerfile                   # Hardened multi-stage build (SEC-007/SCALE-004)
├── compose.yml                  # Resource limits for local testing (SCALE-006)
├── pyproject.toml
├── claude_desktop_config.json   # Example config for Claude Desktop
├── CHANGELOG.md
├── ROADMAP.md                   # Phase plan + accepted-risk register
├── CONTRIBUTING.md              # Contribution guide (English)
├── CONTRIBUTING.de.md           # Contribution guide (German)
├── SECURITY.md                  # Security policy (English)
├── SECURITY.de.md               # Security policy (German)
├── LICENSE
├── README.md                    # This file (English)
└── README.de.md                 # German version

Tool output format

All tools return a structured response envelope (not Markdown text), so MCP clients receive structuredContent they can parse directly:

{
  "source": "Kanton Zürich Rechtssammlung — HuggingFace … & zh.ch",
  "provenance": "cache",          // cache | live | parser | cache+parser | none
  "result_type": "law_summaries", // law_summaries | law_detail | articles | metadata | cache_status
  "count": 2,
  "message": null,                // human-readable guidance for empty/edge results
  "results": [ /* typed items */ ]
}

---

Known Limitations

• HuggingFace dataset: The html_content field is unreliable (cross-contaminated between laws); the server uses pdf_content instead, which is correct but has PDF extraction artefacts (hyphenation, layout artefacts)
• Article parser: PDF text extraction sometimes merges article boundaries; complex nested articles may not parse perfectly
• Initial load: First start requires ~25s to download and index 974 laws from HuggingFace (~38 MB SQLite database)
• zh.ch metadata: No official API; metadata extraction relies on HTML patterns that may change
• Offline mode: Full-text search works offline after initial load; live metadata requires internet
• The corpus is frozen at 2023-01-01. This is the limitation that matters most for a legal server, and it was the one not stated. The newest version in the entire dataset carries version_active_since = 2023-01-01; the HuggingFace dataset itself was last touched 2024-10-10. The 24-hour cache TTL and provenance="cache" describe where an answer came from, not how old the laws in it are. Every response now carries corpus_as_of and corpus_note alongside provenance.
• Repeals after the cut-off are invisible. All 974 entries carry is_active = True and not one has a version_inactive_since. That is not a server bug — the source lists only the statutes in force at snapshot time. The consequence is what matters: a law repealed since then still appears to be in force. Consult the ZH-Lex permalink for the operative text.
• zhlaw_update_cache does not make the laws newer. It re-downloads the same frozen dataset. Its docstring previously read "only call when law search results seem outdated", which suggested exactly the effect it does not have.

---

Safety & Limits

To report a vulnerability, see the Security Policy.

---

Testing

# Unit + contract tests (no network) — this is what CI runs
PYTHONPATH=src pytest tests/ -m "not live"

# Live tests against zh.ch and HuggingFace
PYTHONPATH=src pytest tests/ -m "live"

# Re-measure the corpus date and the live hosts
PYTHONPATH=src python scripts/record_fixtures.py

150 tests — 142 offline, 8 live. Eight tools, eight live tests: the best coverage in this portfolio, which is why the finding here is not about mechanics but about a confusion between two questions. provenance="cache" answers where an answer came from; corpus_as_of answers how old the laws in it are. Only the first was ever answered, and the second is the one a user means when they ask "is this current?".

A measurement limit, deliberately not resolved by editing a test

test_live_get_law_metadata fails in the recording environment: zhlex.zh.ch is not reachable from it. Nothing follows from that. Public DNS resolves the host (NOERROR, 194.247.8.174) and an NXDOMAIN control shows the query discriminates — so the limit is the environment's, not the source's.

The test was therefore left untouched. A test you see red because your own network cannot get out is not a test to rewrite; rewriting it would leave you measuring your own environment instead of the source. PROVENANCE.md records this as open.

---

Changelog

See CHANGELOG.md

---

Roadmap

See ROADMAP.md

---

Contributing

See CONTRIBUTING.md

---

Security

See SECURITY.md

---

License

MIT License — see LICENSE

---

Author

Hayal Oezkan · malkreide

---

Credits & Related Projects

• Data: rcds/swiss_legislation — HuggingFace dataset (CC-BY-SA 4.0)
• ZH-Lex: zh.ch Gesetzessammlung — Official Canton Zurich legal collection
• LexFind: lexfind.ch — Cross-cantonal legislation database
• Protocol: Model Context Protocol — Anthropic / Linux Foundation
• Related: swiss-courts-mcp — Law text + case law = complete legal research
• Related: zurich-opendata-mcp — Law text + city council decisions = full context
• Portfolio: Swiss Public Data MCP Portfolio

Installation

Run via uv's uvx — no clone or manual install needed. Add to your MCP client config (mcpServers for Claude Desktop, Cursor and Windsurf; use a top-level servers key for VS Code in .vscode/mcp.json):

{
  "mcpServers": {
    "openlex-mcp": {
      "command": "uvx",
      "args": [
        "openlex-mcp"
      ]
    }
  }
}