i14y-mcp 0.2.0__tar.gz

i14y_mcp-0.2.0/.dockerignore

@@ -0,0 +1,19 @@
+.git/
+.github/
+.venv/
+venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+tests/
+docs/
+audits/
+*.md
+!README.md
+compose.yaml

i14y_mcp-0.2.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  # Python dependencies (incl. the mcp SDK — keep protocol support current)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "dependencies"
+      - "ci"

i14y_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.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        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/

i14y_mcp-0.2.0/.github/workflows/live.yml

@@ -0,0 +1,25 @@
+name: Live API tests
+
+# OPS-001: the live suite hits the real I14Y API, so it is excluded from PR CI
+# and run on a schedule (and on demand) instead.
+on:
+  schedule:
+    - cron: "17 5 * * 1"  # Mondays, 05:17 UTC
+  workflow_dispatch:
+
+jobs:
+  live:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run live tests
+        run: PYTHONPATH=src pytest tests/ -m live -v

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

@@ -0,0 +1,84 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/i14y-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
+        with:
+          skip-existing: true
+
+  publish-mcp:
+    name: Publish to MCP Registry
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for MCP Registry Trusted Publishing (OIDC)
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Sync server.json version to the release tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' \
+            server.json > server.tmp && mv server.tmp server.json
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Authenticate to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish server to MCP Registry
+        run: ./mcp-publisher publish

i14y_mcp-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env

i14y_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-07-24
+
+First production-ready release. Aligns the repository with the Swiss Public Data
+MCP portfolio, runs a full MCP best-practice audit, and remediates all findings.
+
+**Audit verification:** production-ready ✅ — run-id
+`2026-07-24T091742-Z-i14y-mcp`, catalog hash `091f446b2796…`, results 36 pass ·
+0 fail · 5 non-blocking partials · 3 todo. Details under
+[`audits/`](audits/2026-07-24T091742-Z-i14y-mcp/audit-report.md).
+
+### Added
+- Portfolio-standard repository scaffolding to align with the other Swiss Public
+  Data MCP servers: `Dockerfile`, `compose.yaml`, `claude_desktop_config.json`,
+  `.dockerignore`, `.gitignore`, and a `server.json` manifest for the MCP Registry.
+- GitHub Actions workflows: `ci.yml` (matrix 3.10–3.13), `live.yml` (scheduled
+  live API suite), `publish.yml` (PyPI + MCP Registry via OIDC Trusted Publishing),
+  plus `.github/dependabot.yml`.
+- Contributor and security documentation: `CONTRIBUTING.md` / `CONTRIBUTING.de.md`,
+  `SECURITY.md` / `SECURITY.de.md`, and `PUBLISHING.md`.
+- MCP best-practice audit results under `audits/` (44 checks, 19 findings).
+- `docs/roadmap.md` documenting the Read-only-First phase architecture (OPS-003).
+- `HEALTHCHECK` in the Docker image so orchestrators can detect an unhealthy
+  container (SCALE-004).
+- Structured JSON logging on stderr via `structlog`, with per-request severity
+  levels (OBS-003).
+- `Context` injection across all tools for client-visible progress/logging, with
+  per-endpoint progress in `api_status` (SDK-003).
+- `search_catalog` now returns a `match_type` and an actionable `hint` on an empty
+  result instead of a bare empty list (ARCH-003).
+- `docs/network-egress.md` documenting the code- and network-layer egress
+  controls (SEC-021).
+- `tool-definitions.lock.json`, a committed hash snapshot of the tool set and
+  each tool's argument surface (names + required), verified by a test as a
+  rug-pull guard that is stable across SDK patch upgrades (SEC-022).
+- README sections on MCP primitives (tools-only rationale, ARCH-008) and the MCP
+  protocol version / update policy (ARCH-012).
+- Container FD `ulimits` and a memory reservation in `compose.yaml` (SCALE-006).
+- All tool annotations now also set `idempotentHint: true` and
+  `openWorldHint: true` (every tool is a side-effect-free GET against an external
+  API), alongside the existing `readOnlyHint`/`destructiveHint` (ARCH-009).
+- Second audit run under `audits/` confirming production-readiness (36 pass, 5
+  residual non-blocking partials, 0 fail).
+- Tests for the shared client, error masking, CORS session-header exposure, empty
+  search hints, boundary input rejection, egress control and tool-lock integrity.
+
+### Changed
+- **HTTP transports now default to `HOST=127.0.0.1` (loopback)** instead of
+  `0.0.0.0`; binding to all interfaces is an explicit opt-in and warns on stderr
+  outside a container (SEC-016). The Docker image sets `HOST=0.0.0.0` on purpose;
+  remote/PaaS deployments must set it explicitly.
+- A single pooled `httpx.AsyncClient` is now created once in a FastMCP lifespan and
+  reused across tool calls instead of being rebuilt per call (SDK-001).
+- Tool arguments now carry strict schema constraints (`ge`/`le`, `min_length`,
+  whitelist `pattern` on IDs), so malformed input is rejected at the boundary
+  instead of silently clamped (SEC-018).
+- The anchor demo query is now answered in two tool calls; `get_dataset` is
+  documented as the aggregated detail tool (ARCH-007).
+
+### Fixed
+- SSE / streamable-http now sets CORS to expose the `Mcp-Session-Id` header, so
+  browser MCP clients keep their session (SDK-004).
+- Upstream failures surface actionable execution errors (pointing at
+  `api_status` / `search_catalog`), covered by execution- and protocol-error
+  tests (OBS-001).
+
+### Security
+- Upstream 4xx error bodies are no longer embedded verbatim in client-facing
+  errors; a categorised message (HTTP status + path) is surfaced instead (OBS-002).
+- Code-layer egress allow-list (`ALLOWED_HOSTS` frozenset) with
+  `follow_redirects=False`, refusing any off-host redirect (SEC-021).
+
+## [0.1.0] — 2026-07-21
+
+### Added
+- Initial release. 13 read-only tools over the I14Y interoperability platform:
+  `search_catalog`, `list_datasets`, `get_dataset`, `get_dataset_distributions`,
+  `list_data_services`, `get_data_service`, `list_public_services`,
+  `list_concepts`, `get_concept`, `search_codelist_entries`, `list_publishers`,
+  `list_catalogs`, `api_status`.
+- Dual transport: stdio and streamable-http/SSE via `I14Y_MCP_TRANSPORT`.
+- Retry with exponential backoff (2s/4s/8s); 4xx other than 429 fail fast.
+- Pydantic v2 response envelope carrying `source` and `provenance`.
+- Bilingual documentation (EN/DE) and full probe report in `docs/probe-i14y.md`.
+
+### Known findings
+Discovered during the live probe on 2026-07-21. Recorded here so the next
+server in the portfolio does not have to rediscover them.
+
+- **The search parameter is `query`, not `q`.** Unknown query parameters are
+  silently discarded and the endpoint returns the entire index — a 15 MB
+  response with HTTP 200. The API never says no; it says everything.
+- **`page` and `pageSize` are ignored on `/api/search`.** The complete result
+  set is always returned. Capping must happen client-side.
+- **The `types` filter on search only works for `Dataset`.** `Concept`,
+  `DataService`, `PublicService` and `MappingTable` are accepted without error
+  but yield zero results, although those entities exist.
+- **The search index covers about 51 % of the register** (1013 of ~2003
+  datasets). Search is the entry point, `list_datasets` the completeness
+  guarantee.
+- **Multilingual nesting is inconsistent.** Themes wrap their language object
+  under `name`, keywords under `label`, titles sit directly as
+  `{de, fr, it, en}`. A naive extractor leaks a dict into a string field.
+  Caught by a live test, not by unit tests.
+- **`endpointUrls` may contain entries without a URI**, carrying only a label
+  such as «OpenAPI Spezifikation». These are surfaced, not dropped.
+- **`/api/concepts/{id}/codelist-entries` returns 405.** Only the `/search`
+  subpath exists, and it requires `language` (HTTP 400 otherwise).
+- **Read endpoints need no authentication**, despite the OpenAPI document
+  declaring a Bearer scheme. Write endpoints do.
+
+[Unreleased]: https://github.com/malkreide/i14y-mcp/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/malkreide/i14y-mcp/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/malkreide/i14y-mcp/releases/tag/v0.1.0

i14y_mcp-0.2.0/CONTRIBUTING.de.md

@@ -0,0 +1,42 @@
+# Mitwirken
+
+[🇬🇧 English Version](CONTRIBUTING.md)
+
+Danke für dein Interesse an `i14y-mcp`. Dies ist ein Read-only-MCP-Server über
+die öffentliche I14Y-API; Beiträge sollen das so belassen.
+
+## Grundregeln
+
+- **Read-only.** Jedes Tool bleibt mit `readOnlyHint: true` und
+  `destructiveHint: false` annotiert. Keine Schreib-, Sende- oder
+  Dateisystem-Fähigkeit. Schreib-Endpunkte existieren in der Quell-API, werden
+  hier aber bewusst nicht exponiert.
+- **Nur ein Egress-Host.** Anfragen gehen ausschliesslich an die fixe Basis-URL
+  `https://api.i14y.admin.ch/api`, erzwungen durch die `ALLOWED_HOSTS`-Allow-List
+  in `src/i14y_mcp/client.py` (siehe [`docs/network-egress.md`](docs/network-egress.md));
+  keine nutzergesteuerten URLs, daher keine SSRF-Angriffsfläche.
+- **Keine Secrets.** Die Lese-Endpunkte sind unauthentifiziert; keine
+  Credential-Verarbeitung hinzufügen.
+
+## Entwicklung
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+PYTHONPATH=src pytest tests/ -m "not live"   # offline, respx-gemockt
+PYTHONPATH=src pytest tests/ -m live         # gegen die echte API
+ruff check src tests
+```
+
+## Pull Requests
+
+- Tests für nutzersichtbare Änderungen ergänzen; `ruff check` und die
+  Offline-Suite grün halten.
+- Einen `CHANGELOG.md`-Eintrag unter `[Unreleased]` hinzufügen.
+- Bei Doku-Änderungen sowohl `README.md` als auch `README.de.md` aktualisieren.
+- Für Release/Publishing siehe [`PUBLISHING.md`](PUBLISHING.md).
+
+## Sicherheitsprobleme melden
+
+Siehe [`SECURITY.md`](SECURITY.md) — bitte privat melden, keine öffentlichen Issues.

i14y_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+[🇩🇪 Deutsche Version](CONTRIBUTING.de.md)
+
+Thanks for your interest in `i14y-mcp`. This is a read-only MCP server over the
+public I14Y API; contributions should keep it that way.
+
+## Ground rules
+
+- **Read-only.** Every tool stays annotated `readOnlyHint: true`,
+  `destructiveHint: false`. No write, send, or filesystem capability. Write
+  endpoints exist in the upstream API but are deliberately not exposed.
+- **One egress host.** Requests go only to the fixed base URL
+  `https://api.i14y.admin.ch/api`, enforced by the `ALLOWED_HOSTS` allow-list in
+  `src/i14y_mcp/client.py` (see [`docs/network-egress.md`](docs/network-egress.md));
+  no user-supplied URLs, so there is no SSRF surface.
+- **No secrets.** The read endpoints are unauthenticated; do not add credential
+  handling.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+PYTHONPATH=src pytest tests/ -m "not live"   # offline, respx-mocked
+PYTHONPATH=src pytest tests/ -m live         # hits the real API
+ruff check src tests
+```
+
+## Pull requests
+
+- Add tests for user-facing changes; keep `ruff check` and the offline suite green.
+- Add a `CHANGELOG.md` entry under `[Unreleased]`.
+- Update both `README.md` and `README.de.md` for any documentation change.
+- For release/publishing, see [`PUBLISHING.md`](PUBLISHING.md).
+
+## Reporting security issues
+
+See [`SECURITY.md`](SECURITY.md) — please use private reporting, not public issues.

i14y_mcp-0.2.0/Dockerfile

@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1.7
+# Multi-stage build: install deps with pip into a venv, then ship a slim runtime.
+FROM python:3.14-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+# LICENSE must be copied — pyproject.toml declares `license = { file = "LICENSE" }`,
+# so the wheel build fails without it.
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ ./src/
+
+RUN python -m venv /app/.venv \
+    && /app/.venv/bin/pip install --no-cache-dir .
+
+# ---------------------------------------------------------------------------
+
+FROM python:3.14-slim AS runtime
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PATH="/app/.venv/bin:$PATH" \
+    I14Y_MCP_TRANSPORT=sse \
+    HOST=0.0.0.0 \
+    PORT=8000
+
+RUN groupadd --system mcp \
+    && useradd --system --gid mcp --home-dir /app --shell /usr/sbin/nologin mcp
+
+WORKDIR /app
+COPY --from=builder --chown=mcp:mcp /app/.venv /app/.venv
+
+USER mcp
+EXPOSE 8000
+
+# SCALE-004: let orchestrators/load balancers detect an unhealthy container.
+# The SSE runtime opens PORT; a successful TCP connect means the server is up.
+# Uses stdlib only (no curl in the slim image).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import os,socket; socket.create_connection(('127.0.0.1', int(os.getenv('PORT','8000'))), 3).close()" || exit 1
+
+# Read-only, no-auth public-data server — no secrets required at runtime.
+CMD ["python", "-m", "i14y_mcp.server"]

i14y_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.