bag-epl-mcp 0.2.0__tar.gz

bag_epl_mcp-0.2.0/.dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+.venv
+__pycache__
+*.py[cod]
+*.egg-info
+dist
+build
+.pytest_cache
+.ruff_cache
+htmlcov
+.coverage
+tests
+docs
+*.md
+!README.md

bag_epl_mcp-0.2.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+# ARCH-012: automatisierte monatliche Update-Vorschlaege fuer Abhaengigkeiten.
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+    groups:
+      python-deps:
+        patterns: ["*"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "ci"

bag_epl_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          PYTHONPATH=src pytest tests/ -m "not live"
+
+      - name: Lint
+        run: ruff check src/ tests/

bag_epl_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Snapshot tool-definition hashes (SEC-022)
+        # NB: write outside dist/ — the publish step runs twine over every file
+        # in the downloaded dist/ artifact and rejects non-distribution files.
+        run: |
+          pip install -e .
+          mkdir -p tool-hashes
+          PYTHONPATH=src python scripts/snapshot_tool_hashes.py tool-hashes/tool-hashes.json
+          cat tool-hashes/tool-hashes.json
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload tool-definition hashes
+        uses: actions/upload-artifact@v7
+        with:
+          name: tool-hashes
+          path: tool-hashes/tool-hashes.json
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/bag-epl-mcp/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bag_epl_mcp-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.env
+.venv
+*.egg

bag_epl_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-01
+
+### Added
+- **Env-based transport selection** (`MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT`):
+  the Streamable HTTP transport for cloud deployment is now actually
+  implemented (previously only documented). Default remains `stdio`.
+- CORS middleware on the HTTP transport exposing `Mcp-Session-Id` for browser
+  clients (claude.ai), with an explicit origin allow-list (`MCP_CORS_ORIGINS`).
+- Tool annotations (`readOnlyHint`, `openWorldHint`) on all six tools.
+- Egress allow-list guard (`ALLOWED_HOSTS` + `_assert_safe_url`): HTTPS-only,
+  host allow-list, and resolved-IP blocklist (SSRF protection) before any
+  outbound request.
+- `docs/SECURITY.md` — threat model (Lethal-Trifecta assessment, no-auth/
+  session rationale, egress and host-binding policy).
+- `[http]` optional dependency group (`uvicorn`, `starlette`).
+- **Multi-stage `Dockerfile`** (slim base, non-root UID 10001, `HEALTHCHECK`)
+  and `render.yaml` Blueprint with health check and resource plan.
+- `/healthz` HTTP endpoint for load-balancer probes.
+- **Lifespan-managed pooled `httpx.AsyncClient`** (connection reuse / keep-alive)
+  instead of a fresh client per request.
+- **Structured JSON logging** via `structlog`, written to **stderr** (stdout
+  stays reserved for the stdio JSON-RPC stream); full error detail is logged
+  server-side while the model only sees a sanitized message.
+- `$PORT` fallback for `MCP_PORT` (PaaS/Render compatibility).
+- **Structured response envelope** for tool JSON output: `source`, `provenance`
+  (incl. `license`), `match_type`, `count`, `results` (SDK-002, ARCH-003).
+- **OGD-CH attribution** (CC BY 4.0) in every tool response — JSON `provenance`
+  block and Markdown source/licence footer (CH-004).
+- `<use_case>` tags in all tool docstrings (ARCH-002).
+- `protocolVersion` constant + update policy; surfaced via `epl_server_info`
+  (ARCH-012); `.github/dependabot.yml` for monthly pip / actions updates.
+- `docs/ROADMAP.md` with phase gates and sign-offs (OPS-003); data-flow
+  architecture diagram in both READMEs (OPS-002).
+- Optional OpenTelemetry tracing (`[otel]` extra, `MCP_OTEL_ENABLED`) — OBS-006.
+- `scripts/snapshot_tool_hashes.py` + release-workflow step recording SHA-256
+  hashes of tool definitions (SEC-022).
+- Tests split into `tests/test_unit.py` (mocked) and `tests/test_live.py`
+  (opt-in, one per tool) with a shared `conftest.py` (OPS-001).
+- `ctx: Context` injection in all tools + per-tool-call bound structured logging
+  context (`tool`, `correlation_id`, `request_id`/`client_id`) — SDK-003 / OBS-003.
+- **Structured tool output (SDK-002):** all 6 tools now declare typed Pydantic
+  output schemas and return `structuredContent` alongside the curated Markdown
+  (`content`) — a hybrid `CallToolResult`, so machine consumers get a validated
+  schema with no loss of the human-readable output.
+- **OpenTelemetry on by default (OBS-006):** `MCP_OTEL_ENABLED` now defaults to
+  on; a silent no-op when the `[otel]` extra isn't installed (base installs and
+  stdout are unaffected). `TracerProvider` + OTLP exporter +
+  Starlette/httpx auto-instrumentation; set `MCP_OTEL_ENABLED=0` to disable.
+- **DNS-pinned HTTP transport** (`_PinnedNetworkBackend`): the host is resolved
+  exactly once, the resolved IP is validated and the TCP connection pinned to it,
+  while TLS SNI/cert verification still use the hostname — eliminates the
+  resolve/connect TOCTOU (SEC-005).
+- `deploy/haproxy.cfg`: reference sticky-session (Mcp-Session-Id stick-table +
+  TTL) config for the horizontal-scaling path (SCALE-002/003).
+
+### Changed
+- Console entrypoint is now `bag_epl_mcp.server:main` (transport-aware).
+- Configuration via a `pydantic-settings` `ServerSettings` object instead of
+  module-level transport globals.
+- Errors now surface as MCP `isError` results (raised `ToolError`); the generic
+  error path no longer echoes raw exception messages to the model.
+- Corrected README/README.de deployment instructions to the real
+  env-var-based mechanism and the `/mcp` endpoint.
+- Input models now use Pydantic `strict=True` (the `format` field stays lenient
+  so clients may pass the string `"json"`/`"markdown"`) — SEC-018.
+
+### Security
+- Addresses audit findings SCALE-001, ARCH-009, SDK-004, SEC-004/005/021,
+  SEC-016, SEC-019, SEC-009, OBS-001/002 (Phase 1); SEC-007, SCALE-004,
+  SCALE-006, SDK-001, OBS-003 (Phase 2); and SEC-018, SEC-022, ARCH-002,
+  ARCH-012, SDK-002, ARCH-003, CH-004, OBS-006, OPS-001/002/003 (Phase 3);
+  and SDK-003, OBS-003, SEC-005, SDK-002, OBS-006 (post-re-audit follow-up). See
+  `docs/audit/2026-06-01/` and `docs/audit/2026-06-01-reaudit/`.
+
+## [0.1.0] - 2026-04-13
+
+### Added
+- Initial release with Phase 1 implementation (no authentication required)
+- **SL module**: `epl_sl_suche` — search the Spezialitaetenliste
+- **GGSL module**: `epl_ggsl_abfrage` — check congenital disorder coverage
+- **MiGeL module**: `epl_migel_suche` — search medical devices
+- **Transparency**: `epl_gesuchseingaenge` — pending SL admission requests
+- **Legal context**: `epl_rechtskontext` — WZW criteria, KVG/KLV/IVG references
+- **Server info**: `epl_server_info` — status and phase information
+- 2 Resources: `epl://uebersicht`, `epl://rechtsrahmen`
+- 2 Prompts: `epl_kassenpflicht_check`, `epl_schulgesundheit_recherche`
+- Dual transport: stdio (Claude Desktop) + Streamable HTTP (cloud/Render.com)
+- GitHub Actions CI (Python 3.11, 3.12, 3.13)
+- Bilingual documentation (DE/EN)
+- Unit and integration tests (mocked HTTP via respx)

bag_epl_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to bag-epl-mcp
+
+Thank you for your interest in contributing! This server is part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide).
+
+---
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/malkreide/bag-epl-mcp/issues) to report bugs or request features.
+
+Please include:
+- Python version and OS
+- Full error message or description of unexpected behaviour
+- Steps to reproduce
+
+---
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/your-feature`
+3. Make your changes and add tests
+4. Ensure all tests pass: `PYTHONPATH=src pytest tests/ -m "not live"`
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/): `feat: add new tool`
+6. Push and open a Pull Request against `main`
+
+---
+
+## Code Style
+
+- Python 3.11+
+- [Ruff](https://github.com/astral-sh/ruff) for linting and formatting
+- Type hints required for all public functions
+- Tests required for new tools (`tests/test_server.py`)
+- Follow the existing FastMCP / Pydantic v2 patterns in `server.py`
+
+---
+
+## Data Sources
+
+This server accesses Swiss BAG (Federal Office of Public Health) data — all without authentication:
+
+| Source | Documentation |
+|--------|--------------|
+| Spezialitaetenliste (SL) | [sl.bag.admin.ch](https://sl.bag.admin.ch) |
+| GGSL | [BAG GGSL Info](https://www.bag.admin.ch) |
+| MiGeL | [BAG MiGeL Info](https://www.bag.admin.ch) |
+
+### Phase 2: FHIR API
+
+When the BAG publishes its FHIR/IDMP API for the ePL, contributions updating the tools to use it are very welcome. The architecture is designed to make this upgrade minimal — see the `FHIR_BASE_URL` constant and the `_sl_website_suche` function in `server.py`.
+
+When adding new data sources, follow the **No-Auth-First** principle: Phase 1 uses only open, authentication-free endpoints. Authenticated APIs are introduced in later phases with graceful degradation.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

bag_epl_mcp-0.2.0/Dockerfile

@@ -0,0 +1,38 @@
+# ── Multi-Stage-Build (SCALE-004) ───────────────────────────────────────────────
+# Stage 1: Abhaengigkeiten in ein venv installieren.
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+ENV PIP_NO_CACHE_DIR=1 PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Nur die fuer den Build noetigen Dateien kopieren (siehe .dockerignore).
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN python -m venv /opt/venv \
+    && /opt/venv/bin/pip install --upgrade pip \
+    && /opt/venv/bin/pip install ".[http]"
+
+# ── Stage 2: schlankes Runtime-Image ────────────────────────────────────────────
+FROM python:3.12-slim AS runtime
+
+# SEC-007: Non-Root-User (UID >= 10000), keine Root-Rechte zur Laufzeit.
+RUN groupadd -r -g 10001 app && useradd -r -g app -u 10001 -d /home/app -m app
+
+COPY --from=builder /opt/venv /opt/venv
+
+ENV PATH="/opt/venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    MCP_TRANSPORT=streamable-http \
+    MCP_HOST=0.0.0.0 \
+    MCP_PORT=8000
+
+USER app
+EXPOSE 8000
+
+# SCALE-004: HEALTHCHECK fuer Load-Balancer-Integration (nutzt /healthz).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import os,urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/healthz' % os.environ.get('MCP_PORT','8000'), timeout=3)" || exit 1
+
+CMD ["python", "-m", "bag_epl_mcp.server"]

bag_epl_mcp-0.2.0/EXAMPLES.md

@@ -0,0 +1,81 @@
+# Use Cases & Examples — bag-epl-mcp
+
+Real-world queries by audience. Indicate per example whether an API key is required.
+
+## 🏫 Bildung & Schule
+Lehrpersonen, Schulbehörden, Fachreferent:innen
+
+### Abklärung von Hilfsmitteln für den Schulalltag
+«Zahlt die Krankenkasse das Hörgerät für einen Schüler oder müssen das die Eltern übernehmen?»
+
+→ epl_migel_suche(suchbegriff="Hoergeraet")
+→ epl_rechtskontext(frage="Zahlt die Grundversicherung Hörgeräte für Kinder?")
+Warum nützlich: Hilft Lehrpersonen und Heilpädagog:innen schnell zu klären, welche Unterstützungsmöglichkeiten für Inklusionsmaterialien über die Grundversicherung bestehen. (Kein API-Key erforderlich)
+
+### Medikamentengabe bei chronischen Erkrankungen im Schullager
+«Wird Ritalin (Methylphenidat) von der Grundversicherung bezahlt und welche Regeln gelten?»
+
+→ epl_sl_suche(suchbegriff="Methylphenidat")
+→ epl_rechtskontext(frage="WZW Kriterien für ADHS Medikamente")
+Warum nützlich: Unterstützt Schulleitungen und Lagerleitende dabei, den gesetzlichen und finanziellen Rahmen von häufigen Dauermedikationen bei Schulkindern zu verstehen. (Kein API-Key erforderlich)
+
+## 👨👩👧 Eltern & Schulgemeinde
+Elternräte, interessierte Erziehungsberechtigte
+
+### Übernahme bei Geburtsgebrechen
+«Mein Kind hat Zystische Fibrose (Geburtsgebrechen 404). Werden die speziellen Medikamente von der IV bezahlt?»
+
+→ epl_ggsl_abfrage(geburtsgebrechen_nr="404")
+→ epl_rechtskontext(frage="Medikamente bei Geburtsgebrechen IVG")
+Warum nützlich: Gibt betroffenen Eltern konkrete Anhaltspunkte, ob wichtige, dauerhafte Medikationen von der IV über die GGSL übernommen werden. (Kein API-Key erforderlich)
+
+### Kosten für Hilfsmittel
+«Wird eine Gehhilfe oder ein Rollstuhl für mein Kind von der Krankenkasse übernommen?»
+
+→ epl_migel_suche(suchbegriff="Rollstuhl")
+Warum nützlich: Erleichtert Eltern den Zugang zu Informationen, welche medizinischen Hilfsmittel in der MiGeL gelistet und somit kassenpflichtig sind. (Kein API-Key erforderlich)
+
+## 🗳️ Bevölkerung & öffentliches Interesse
+Allgemeine Öffentlichkeit, politisch und gesellschaftlich Interessierte
+
+### Transparenz bei neuen Medikamenten
+«Welche neuen Medikamente sind aktuell zur Aufnahme in die Spezialitätenliste beantragt?»
+
+→ epl_gesuchseingaenge()
+Warum nützlich: Bietet der Öffentlichkeit und Medienschaffenden Transparenz darüber, welche neuen Therapien auf Zulassung zur Kassenpflicht warten. (Kein API-Key erforderlich)
+
+### Verständnis der Kassenpflicht (WZW)
+«Nach welchen Kriterien entscheidet das BAG eigentlich, ob ein neues Medikament von allen Prämienzahlern bezahlt wird?»
+
+→ epl_rechtskontext(frage="Nach welchen Kriterien wird über die Aufnahme in die Spezialitätenliste entschieden?")
+Warum nützlich: Fördert das demokratische Verständnis für gesundheitspolitische Entscheide und die Beurteilung nach Wirksamkeit, Zweckmässigkeit und Wirtschaftlichkeit. (Kein API-Key erforderlich)
+
+## 🤖 KI-Interessierte & Entwickler:innen
+MCP-Enthusiast:innen, Forscher:innen, Prompt Engineers, öffentliche Verwaltung
+
+### Integration von Bundesrecht und Gesundheitsdaten
+«Zeige mir die Medikamente in der Spezialitätenliste für Diabetes und gib mir direkt den genauen Fedlex-Link zum Krankenversicherungsgesetz (KVG) betreffend Leistungen.»
+
+→ epl_sl_suche(suchbegriff="Insulin")
+→ fedlex_suche(suchbegriff="Krankenversicherungsgesetz KVG Leistungen") (via https://github.com/malkreide/fedlex-mcp)
+Warum nützlich: Demonstriert eindrücklich, wie fachspezifische Gesundheitsdaten automatisiert mit der primären Rechtsquelle (Fedlex) aus dem Swiss Public Data Portfolio verknüpft werden können. (Kein API-Key erforderlich)
+
+### Automatisierter Kassenpflicht-Check
+«Erstelle mir eine Übersicht der rechtlichen Grundlagen zur MiGeL und suche nach Inkontinenzhilfen.»
+
+→ epl_rechtskontext(frage="Rechtliche Grundlagen MiGeL")
+→ epl_migel_suche(suchbegriff="Inkontinenz")
+Warum nützlich: Erlaubt Entwickler:innen den Bau von automatisierten Systemen für Patientenanfragen, um Kassenpflicht und Gesetze direkt abzugleichen. (Kein API-Key erforderlich)
+
+---
+
+## 🔧 Technische Referenz: Tool-Auswahl nach Anwendungsfall
+
+| Ich möchte… | Tool(s) | Auth nötig? |
+|---|---|---|
+| prüfen, ob ein Medikament kassenpflichtig ist | `epl_sl_suche` | Nein |
+| schauen, ob die IV Medikamente für ein Geburtsgebrechen zahlt | `epl_ggsl_abfrage` | Nein |
+| die Kassenpflicht für Hilfsmittel (z.B. Rollstuhl) klären | `epl_migel_suche` | Nein |
+| wissen, welche Medikamente auf die SL-Zulassung warten | `epl_gesuchseingaenge` | Nein |
+| die rechtlichen Kriterien (z.B. WZW, KVG) verstehen | `epl_rechtskontext` | Nein |
+| den Server-Status und geplante ePL-Phasen abfragen | `epl_server_info` | Nein |

bag_epl_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 malkreide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.